Card#

A container that groups related content with an elevated background and border. Cards automatically step the background surface at each nesting level, alternating between card and card_raised to keep adjacent levels visually distinct without runaway drift.

Usage#

Accents#

Pass an accent= token to tint the card border and give the interior a subtle accent wash. Without accent= the card renders with a neutral border and the next surface step.

with bs.Card(accent="primary", padding=16, gap=8):
    bs.Label("Primary", accent="primary", font="heading-sm")
    bs.Label("Card content")

Layout modes#

layout='vstack' (default) stacks children vertically. 'hstack' places them side by side. 'grid' arranges children in a column-row grid.

# Default vertical stack
with bs.Card(padding=12, gap=8):
    bs.Label("VStack (default)", font="heading-sm")
    bs.Label("First item")
    bs.Label("Second item")
    bs.Label("Third item")

# Horizontal Stack
with bs.Card(layout="hstack", padding=12, gap=12, anchor_items="center"):
    bs.Label("HStack", font="heading-sm")
    bs.Label("A")
    bs.Label("B")
    bs.Label("C")

# Grid - two equally weighted columns
with bs.Card(layout="grid", columns=2, padding=12, gap=8, sticky_items="ew"):
    bs.Label("Grid", font="heading-sm")
    bs.Label("2 cols")
    bs.Label("Item A")
    bs.Label("Item B")
    bs.Label("Item C")
    bs.Label("Item D")

Child defaults#

Use fill_items, expand_items, and anchor_items to set a default layout behavior for all children without repeating it on each widget.

with bs.Card(gap=8, fill_items="x"):
    bs.TextField()   # fills horizontally — no fill="x" needed
    bs.TextField()

Nested cards#

Neutral cards alternate between the card and card_raised surface tokens at each nesting level — the first card steps to card, the next to card_raised, the next back to card, and so on. Every level is visually distinct from its parent regardless of nesting depth.

Accent cards behave differently: the accent[subtle] tint is fixed and does not change with depth. The accent color is the identity signal — elevation stepping is not applied.

with bs.Card(padding=50):
    with bs.Card(padding=50):
        with bs.Card(padding=50):
            bs.Label("Nested Cards")

Widget sizing#

All widgets accept self-placement kwargs via **kwargs. The parent container determines which options apply — stack-based parents use stack kwargs, grid-based parents use grid kwargs. Unrecognised keys are silently ignored.

Stack#

Used inside VStack, HStack, App, and other stack containers.

`fill`	Fill direction: `'x'`, `'y'`, `'both'`, or `'none'`.
`expand`	Grow to consume extra space in the parent. `True` or `False`.
`anchor`	Alignment when the widget does not fill the available slot: `'n'`, `'s'`, `'e'`, `'w'`, `'center'`, `'nw'`, etc.
`margin`	External spacing in pixels. Accepts an integer (equal on all sides), a 2-tuple `(horizontal, vertical)`, or a 4-tuple `(left, top, right, bottom)`.
`margin_x`	Horizontal external spacing (left and right). Accepts an integer or a 2-tuple `(left, right)` for asymmetric spacing. Overrides the horizontal component of `margin=`.
`margin_y`	Vertical external spacing (top and bottom). Accepts an integer or a 2-tuple `(top, bottom)` for asymmetric spacing. Overrides the vertical component of `margin=`.

Grid#

Used inside a Grid container.

`row` / `column`	Zero-based row and column indices.
`rowspan` / `columnspan`	Number of rows or columns to span.
`sticky`	Alignment and fill within the grid cell. Any combination of `'n'`, `'s'`, `'e'`, `'w'` — e.g. `'ew'` stretches horizontally, `'nsew'` fills the entire cell.
`margin`	External spacing in pixels. Accepts an integer, a 2-tuple `(horizontal, vertical)`, or a 4-tuple `(left, top, right, bottom)`.
`margin_x`	Horizontal external spacing. Accepts an integer or `(left, right)`.
`margin_y`	Vertical external spacing. Accepts an integer or `(top, bottom)`.

API#

The complete reference for Card lives on the Widgets API page. At a glance:

Card

A card-surface container that groups content with an elevated background and border.

Full Example#

with bs.App(title="Card Demo", padding=20, gap=16) as app:

    # Accent colors
    bs.Label("Accent Borders", font="heading-sm")
    with bs.HStack(gap=12):
        for accent in ("primary", "secondary", "info", "success", "warning", "danger"):
            with bs.Card(accent=accent, padding=12, gap=4):
                bs.Label(accent.title(), font="heading-sm", accent=accent)
                bs.Label("Card content", font="caption")

    # Layout modes
    bs.Label("Layout Modes", font="heading-sm")
    with bs.HStack(gap=12, anchor_items="n"):

        with bs.Card(padding=12, gap=8):
            bs.Label("VStack (default)", font="heading-sm")
            bs.Label("First item")
            bs.Label("Second item")
            bs.Label("Third item")

        with bs.Card(layout="hstack", padding=12, gap=12, anchor_items="center"):
            bs.Label("HStack", font="heading-sm")
            bs.Label("A")
            bs.Label("B")
            bs.Label("C")

        with bs.Card(layout="grid", columns=[1, 1], padding=12, gap=8, sticky_items="ew"):
            bs.Label("Grid", font="heading-sm")
            bs.Label("2 cols")
            bs.Label("Item A")
            bs.Label("Item B")
            bs.Label("Item C")
            bs.Label("Item D")

    # Nested surface stepping
    bs.Label("Nested Cards", font="heading-sm")
    with bs.Card(padding=12, gap=8):
        bs.Label("Outer (card surface)", font="heading-sm")
        with bs.HStack(gap=8):
            with bs.Card(padding=10, gap=4):
                bs.Label("Inner A", font="heading-sm")
                bs.Label("Overlay surface", font="caption")
            with bs.Card(padding=10, gap=4):
                bs.Label("Inner B", font="heading-sm")
                bs.Label("Overlay surface", font="caption")
            with bs.Card(accent="primary", padding=10, gap=4):
                bs.Label("Inner C", font="heading-sm", accent="primary")
                bs.Label("Accent tint", font="caption")

app.run()