`quirl.components.image`¶

An image with placeholder fallback on network error or unset src.

Module Contents¶

Classes¶

`CircularSmartImage`	A themeable circular image that falls back to a placeholder when unset or on network error. The placeholder can be a URL string or another component (e.g. an icon, a Label, a Spinner).
`SmartImage`	A themeable image that falls back to a placeholder when unset or on network error. The placeholder can be a URL string or another component (e.g. an icon, a Label, a Spinner).
`SmartImagePlaceholder`	Generic fallback placeholder used by SmartImage/CircularSmartImage when no placeholder, unset_placeholder, or error_placeholder is supplied. Renders a simple neutral image glyph so an unset or failed image never ends up passing None as a child.

API¶

class quirl.components.image.CircularSmartImage(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: quirl.components.image.SmartImage

A themeable circular image that falls back to a placeholder when unset or on network error. The placeholder can be a URL string or another component (e.g. an icon, a Label, a Spinner).

Required Props:

(none — src is optional; placeholder covers the unset case)

Optional Props:

source: Image source URL. If omitted, the placeholder shows immediately.
placeholder: Fallback (URL string or component) for both unset src and network error, unless overridden below. If neither this nor unset_placeholder/error_placeholder is given, a plain SmartImagePlaceholder is used instead of showing nothing.
unset_placeholder: Shown when src is empty/None. Overrides placeholder.
error_placeholder: Shown when the image fails to load. Overrides placeholder.
alt: Alt text for the image.
fit: object-fit value, defaults to cover.
height: Container height (CSS value).
width: Container width (CSS value).
image_id: Optional id applied to the underlying , so calling code can update .src later (e.g. document.getElementById(image_id).src = url) and have the placeholder swap react live.
lazy: If True, sets the native loading="lazy" attribute so the browser defers fetching until the image nears the viewport. Defaults to False (eager). Only affects the primary image, not placeholders.

Usage:

CircularSmartImage(source="/img/avatar.png", placeholder="/img/default.png")
CircularSmartImage(source="/img/hero.png", placeholder=Icon(name="broken-image"))
CircularSmartImage(unset_placeholder=Spinner(), error_placeholder="/img/broken.png")

… admonition:: Notes

The image, unset placeholder, and error placeholder are all rendered as siblings up front. Visibility is then driven entirely by the ’s own load/error events, so changing .src on the image element at any point after mount (empty -> url, url -> a different url, etc.) is reflected automatically without re-rendering this component.

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.

on_create()[source]¶: Build the circular image plus both placeholders, wiring load/error handlers so visibility reacts live to source changes.

class quirl.components.image.SmartImage(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 themeable image that falls back to a placeholder when unset or on network error. The placeholder can be a URL string or another component (e.g. an icon, a Label, a Spinner).

Required Props: - (none — src is optional; placeholder covers the unset case)

Optional Props: - source: Image source URL. If omitted, the placeholder shows immediately.

- placeholder:
      Fallback (URL string or component) for both unset src
      and network error, unless overridden below. If neither this nor
      unset_placeholder/error_placeholder is given, a plain
      `SmartImagePlaceholder` is used instead of showing nothing.

- unset_placeholder:
      Shown when src is empty/None. Overrides placeholder.

- error_placeholder:
      Shown when the image fails to load. Overrides placeholder.

- alt:
      Alt text for the image.

- fit:
      object-fit value, defaults to cover.

- height:
      Container height (CSS value).

- width:
      Container width (CSS value).

- circular:
      Whether to render the image (and placeholder) as a circle.

- image_id:
      Optional id applied to the underlying <img>, so calling code can
      update `.src` later (e.g. `document.getElementById(image_id).src = url`)
      and have the placeholder swap react live.

- lazy:
      If True, sets the native `loading="lazy"` attribute so the
      browser defers fetching until the image nears the viewport. Defaults
      to False (eager). Only affects the primary image, not placeholders.

Usage:

SmartImage(source="/img/avatar.png", placeholder="/img/default.png")
SmartImage(source="/img/hero.png", placeholder=Icon(name="broken-image"))
SmartImage(unset_placeholder=Spinner(), error_placeholder="/img/broken.png")

… admonition:: Notes

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.

ERROR_ROLE¶: ‘error’

UNSET_ROLE¶: ‘unset’

build_image() → duck.html.components.image.Image[source]¶

Build the underlying image, wired so load/error events toggle which sibling placeholder is visible. Works whether the source is set at construction time or assigned later by other code.

Returns:: An Image component with load/error handoff attached.

build_placeholder(placeholder, role: str, visible: bool) → duck.html.components.container.Container[source]¶

Build a placeholder slot, wrapping a URL string in an Image or rendering a given component directly.

Parameters:

placeholder – A URL string or a component instance.
role – Either UNSET_ROLE or ERROR_ROLE, used to target this placeholder from the image’s load/error handlers.
visible – Whether this placeholder should be shown initially.

Returns:

A Container holding the resolved placeholder content.

docs_preview_kwargs¶: None

on_create()[source]¶: Build the image plus both placeholders, wiring load/error handlers so visibility reacts live to source changes.

class quirl.components.image.SmartImagePlaceholder(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

Generic fallback placeholder used by SmartImage/CircularSmartImage when no placeholder, unset_placeholder, or error_placeholder is supplied. Renders a simple neutral image glyph so an unset or failed image never ends up passing None as a child.

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.

GLYPH_SOURCE¶: “data:image/svg+xml;utf8,<svg xmlns=‘http://www.w3.org/2000/svg’ viewBox=‘0 0 24 24’ fill=‘none’ stro…”

on_create()[source]¶: Build a small centered generic-image glyph.

quirl.components.image¶

Module Contents¶

Classes¶

API¶

`quirl.components.image`¶