Placeholder¶

Placeholder draws a content-shaped loading skeleton. It is the library mapping of Bootstrap 5 placeholder utilities, used to reserve layout while data is in flight so the page does not jump when the real content arrives.

Reach for Placeholder when you know the approximate shape of the result (a title, a few lines, a card body). Use a Spinner when the wait is indeterminate and there is no layout to preserve.

Basic usage¶

placeholder_basic example

def demo() -> None:
    with bs.scope():
        bs.placeholder(animation="glow", color="secondary", size="lg")

Render one or more placeholders in the slot that will hold the real content, then replace them when the request finishes. They are decorative: they should not be the only indication that work is happening if the wait can fail.

Options¶

Animation¶

animation selects the Bootstrap placeholder motion. A glow pulse is the usual choice for cards and list rows; a wave animation reads well on wide blocks such as table bodies. Disable animation when motion would compete with nearby live content or when the user has requested reduced motion at the page level.

placeholder_animation example

def demo() -> None:
    with bs.scope():
        bs.placeholder(animation="glow", color="primary")
        bs.placeholder(animation="wave", color="secondary")

Keep the animation consistent inside a single loading region so the skeleton reads as one surface rather than a mix of effects.

Color¶

color applies a Bootstrap theme color to the skeleton. secondary and light are quiet defaults on white cards. Stronger colors (primary, info) work when the placeholder sits on a tinted header or a dark well. Avoid using color as the only loading signal; the animation already does that job.

Size¶

size controls how large the skeleton paints, matching Bootstrap placeholder sizing. Use a large size for titles and hero lines, and a smaller size for captions, meta rows, and compact table cells. Mixing sizes in one card is useful when you are mirroring a heading-plus-body layout.

placeholder_size example

def demo() -> None:
    with bs.scope():
        bs.placeholder(size="lg", color="secondary", animation="glow")
        bs.placeholder(size="sm", color="secondary", animation="glow")

Stack several placeholders with different sizes to sketch a paragraph. Keep the count close to the real content so the transition from skeleton to data is small.

Loading regions¶

Placeholders belong in the same container that will hold the loaded widgets. Do not park them in a toast or a floating overlay; that hides the layout they are supposed to protect. When a whole page is waiting and has no structure yet, a Spinner is the clearer signal.

Argument reference¶

Property	Type	Default	DBC 2.0.4 name	Support (native)	Support (compat)
children	a list of or a singular dash component, string or number	None	children	supported	supported
id	string	None	id	supported	supported
animation	a value equal to: 'glow', 'wave'	None	animation	supported	supported
color	string	None	color	supported	supported
size	a value equal to: 'xs', 'sm', 'lg'	None	size	supported	supported
button	boolean	False	button	supported	supported
delay_hide	number	0	delay_hide	supported	supported
delay_show	number	0	delay_show	supported	supported
show_initially	boolean	True	show_initially	supported	supported
style	unknown	None	style	supported	supported
class_name	string	None	className	supported	supported
xs	number	None	xs	supported	supported
sm	number	None	sm	supported	supported
md	number	None	md	supported	supported
lg	number	None	lg	supported	supported
xl	number	None	xl	supported	supported
xxl	number	None	xxl	supported	supported
target_components	dict with strings as keys and values of type string \| list of strings	None	target_components	supported	supported
display	a value equal to: 'auto', 'show', 'hide'	'auto'	display	supported	supported
key	string	None	key	unsupported	unsupported
class_name	string	None	className	supported	supported