Image

SmartImage

Component

A themeable image that falls back to a placeholder when unset or on

Required Props

1

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

Optional Props

11

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

python
SmartImage(source='/static/img/uknown.png')

Live Preview

CircularSmartImage

Component

A themeable circular image that falls back to a placeholder when unset or on

Required Props

1

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

Optional Props

10

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

python
CircularSmartImage(source='/static/img/uknown.png')

Live Preview

SmartImagePlaceholder

Component

Generic fallback placeholder used by SmartImage/CircularSmartImage when

Usage

python
SmartImagePlaceholder()

Live Preview