Metadata-Version: 2.4
Name: streamlit-avatar-stack
Version: 0.1.0
Summary: A clickable, stateful avatar stack for Streamlit Components V2
Author-email: Carlos Serrano <sqlinsights@gmail.com>
License-Expression: MIT
Keywords: streamlit,avatar,component
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow>=10
Requires-Dist: streamlit>=1.61.1
Dynamic: license-file

# Streamlit Avatar Stack

A selectable avatar stack built with Streamlit Components V2. It supports names,
Material Symbols, remote images, data URIs, and local image paths.

## Install

```bash
pip install streamlit-avatar-stack
```

For local development:

```bash
uv pip install -e .
```

## Usage

```python
import streamlit as st
from streamlit_avatar_stack import avatar_stack

avatars = [
    "Ada Lovelace",
    ":material/engineering:",
    "https://example.com/avatar.jpg",
    "images/grace.png",
]

selected = avatar_stack(avatars, key="people")
st.write(selected)
```

The component detects each avatar type automatically. Images are cropped to fill
the circle, and invalid images display a fallback icon. Nothing is selected by
default; clicking the selected avatar clears it.

## API reference

```python
avatar_stack(
    avatars,
    *,
    labels=None,
    return_index=True,
    default=None,
    key=None,
    bind=None,
    on_change=None,
    args=(),
    kwargs=None,
    size=48,
    display_max=None,
    horizontal_alignment="right",
    overlap_avatars=True,
    overlap=12,
    random_background=True,
)
```

### Required argument

- `avatars`: A non-empty sequence of names, Material icon strings, image URLs,
  data URIs, or local image paths.

### Optional arguments

- `labels=None`: Tooltip labels in the same order as `avatars`.
- `return_index=True`: Return the selected index; when false, return its label.
- `default=None`: Initially selected index.
- `key=None`: Unique Streamlit component key.
- `bind=None`: Use `"query-params"` for label-based URL binding.
- `on_change=None`: Callback invoked when the selection changes.
- `args=()`: Positional callback arguments.
- `kwargs=None`: Keyword callback arguments.
- `size=48`: Avatar diameter in pixels.
- `display_max=None`: Maximum visible avatars before the `+N` control.
- `horizontal_alignment="right"`: Align the stack to `"left"` or `"right"`.
- `overlap_avatars=True`: Control whether regular avatars overlap.
- `overlap=12`: Overlap distance in pixels.
- `random_background=True`: Use varied avatar backgrounds; false uses the
  theme’s secondary background color.

Avatars wrap automatically. When collapsed, an off-page selection temporarily
replaces the final visible avatar and returns to its original position when
cleared.

## Labels and URL binding

```python
labels = ["Ada", "Engineering", "Grace", "Assistant"]

selected = avatar_stack(
    avatars,
    labels=labels,
    return_index=False,
    key="person",
    bind="query-params",
)
```

Query-parameter binding requires unique `labels`, `return_index=False`, and a
`key`. It synchronizes the selected label in both directions.

## Demo

```bash
uv run streamlit run main.py
```

The demo loads 25 records from `data/avatars.json`, including each avatar’s
label, title, and department, and displays the selected record.

## License

MIT
