Carousel¶

Carousel rotates through a sequence of slides — typically images with an optional header and caption. It is Bootstrap 5's carousel. Use it for hero banners and short media tours, not as a general-purpose tab control (Nav or Accordion fit that job better).

Basic usage¶

The carousel is driven by an items list of dicts. Each dict may include src and alt for the image, plus header and caption for the overlay copy. active_index selects the first slide (0 by default).

carousel_basic example

def demo():
    with bs.scope():
        bs.carousel(
            items=[
                {
                    "src": _slide("#1a365d", "#2b6cb0"),
                    "alt": "Harbor at dawn",
                    "header": "Welcome",
                    "caption": "A short caption for the first slide.",
                },
                {
                    "src": _slide("#276749", "#48bb78"),
                    "alt": "Forest trail",
                    "header": "Explore",
                    "caption": "Call out a second point.",
                },
                {
                    "src": _slide("#4a3728", "#c05621"),
                    "alt": "Studio interior",
                    "header": "Build",
                    "caption": "Close with a third idea.",
                },
            ]
        )

carousel is the snake_case alias for Carousel.

Controls, indicators, and interval¶

controls (default True) renders the previous/next arrows. indicators (default True) renders the dash buttons under the slide. interval accepts an int duration in milliseconds, False to disable auto-advance, or None to leave the default. slide defaults to True for the sliding transition.

carousel_controls_indicators_interval example

def demo():
    with bs.scope():
        bs.carousel(
            items=[
                {"src": _slide("#2a4365", "#3182ce"), "alt": "One", "header": "One"},
                {"src": _slide("#553c2a", "#dd6b20"), "alt": "Two", "caption": "Second slide"},
            ],
            controls=True,
            indicators=True,
            interval=False,
            active_index=0,
            slide=True,
        )

on_change fires when the active slide changes. persist defaults to "off". Keep every item's alt filled in even when the caption already describes the image — the caption is visible copy, alt is for the img.

Argument reference¶

Property	Type	Default	DBC 2.0.4 name	Support (native)	Support (compat)
id	string	None	id	supported	supported
items	list of dicts	None	items	supported	supported
active_index	number	0	active_index	supported	supported
interval	number	None	interval	supported	supported
controls	boolean	True	controls	supported	supported
indicators	boolean	True	indicators	supported	supported
style	unknown	None	style	supported	supported
class_name	string	None	className	supported	supported
slide	boolean	None	slide	supported	supported
variant	a value equal to: 'dark'	None	variant	supported	supported
persistence	boolean \| string \| number	None	persistence	unsupported	unsupported
persisted_props	list of a value equal to: 'active_index's	None	persisted_props	unsupported	unsupported
persistence_type	a value equal to: 'local', 'session', 'memory'	None	persistence_type	unsupported	unsupported
class_name	string	None	className	supported	supported

Notes¶

This component does not take arbitrary slide children; pass the items list. That keeps the slide markup consistent with Bootstrap's carousel internals. See the compatibility page for how the native and dbc surfaces line up.