quirl.components.avatar

A user avatar with image support, initials fallback, and status indicator.

Module Contents

Classes

Avatar

A circular user avatar with image support, initials fallback, and an optional presence status dot.

Data

SIZE_MAP

STATUS_TOKEN_MAP

API

class quirl.components.avatar.Avatar(element: Optional[str] = None, properties: Optional[Dict[str, str]] = None, props: Optional[Dict[str, str]] = None, style: Optional[Dict[str, str]] = None, inner_html: Optional[Union[str, str, float]] = None, children: Optional[List[duck.html.components.HtmlComponent]] = None, **kwargs)[source]

Bases: duck.html.components.container.Container

A circular user avatar with image support, initials fallback, and an optional presence status dot.

Displays a profile image when available, otherwise renders initials centered in a themed circle. The image fades in smoothly once loaded.

Usage:

Avatar(src="/static/user.jpg", alt="Jane Doe", initials="JD", status="online")

Required Props:

  • initials: Fallback text when no image is provided

Optional Props:

  • src: Image source URL

  • alt: Alt text for the image

  • size: One of xs, sm, md, lg, xl. Defaults to md.

  • status: One of online, away, busy, offline. Adds a presence dot.

  • bg_color: Circle background, defaults to var(–theme-accent-color)

  • color: Initials color, defaults to var(–theme-surface-color)

Initialization

Initialize an HTML component.

Parameters:

  • element – The HTML element tag name (e.g., textarea, input, button). Can be None, but make sure element is returned by get_element method.

  • accept_inner_html – Whether the HTML component accepts an inner body (e.g., inner-body-here).

  • inner_html – Inner html to add to the HTML component. Defaults to None.

  • properties – Dictionary for properties to initialize the component with.

  • props – Just same as properties argument (added for simplicity).

  • style – Dictionary for style to initialize the component with.

  • event_handlers – Events to automatically bind. Each dictionary maps an event name to its handler and may include additional keyword arguments forwarded to bind(), e.g. event_handlers=[{"click": on_button_click, **extra_kwargs}].

  • **kwargs – Extra keyword arguments

Raises:

HtmlComponentError – If ‘element’ is not a string or ‘inner_html’ is set but ‘accept_inner_html’ is False.

build_circle(dim: str) → duck.html.components.container.Container[source]

Build the clipped circle holding the image or initials.

Parameters:

dim – Pixel diameter for this avatar’s size.

Returns:

A circular Container with image or initials content.

build_status_dot(status: str, dim: str) → duck.html.components.container.Container[source]

Build the small presence indicator anchored to the avatar’s edge.

Parameters:

  • status – One of online, away, busy, offline.

  • dim – Pixel diameter of the parent avatar.

Returns:

A positioned Container rendering the status dot.

docs_preview_kwargs

None

on_create()[source]

Build the avatar circle plus an optional status dot.

quirl.components.avatar.SIZE_MAP

None

quirl.components.avatar.STATUS_TOKEN_MAP

None