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

pip install streamlit-avatar-stack

For local development:

uv pip install -e .

Usage

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

avatar_stack(
    avatars,
    *,
    key,
    labels=None,
    return_index=True,
    default=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 arguments

• avatars: A non-empty sequence of names, Material icon strings, image URLs, data URIs, or local image paths.
• key: A non-empty, stable Streamlit component key.

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.
• 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

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

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