Label

Static text display with optional icon, semantic font tokens, and accent colors. The display text is the first positional argument.

Usage

Font tokens

Use the font= token string to apply semantic typography. Modifiers like [bold], [italic], and [underline] can be chained. For the full token list and modifier reference see Typography.

bs.Label("Display",  font="display-xl")
bs.Label("Heading",  font="heading-lg")
bs.Label("Body",     font="body")
bs.Label("Caption",  font="caption")
bs.Label("Code",     font="code")

# Modifiers
bs.Label("Bold",        font="body[bold]")
bs.Label("Bold Italic", font="heading-md[italic]")

# Size adjustment relative to base
bs.Label("Larger",  font="body[+2]")
bs.Label("Smaller", font="body[-1]")

Accent colors

Use accent= to apply a semantic text color that adapts to the active theme.

bs.Label("Primary",   accent="primary",   font="body[bold]")
bs.Label("Secondary", accent="secondary", font="body[bold]")
bs.Label("Info",      accent="info",      font="body[bold]")
bs.Label("Success",   accent="success",   font="body[bold]")
bs.Label("Warning",   accent="warning",   font="body[bold]")
bs.Label("Danger",    accent="danger",    font="body[bold]")

Icons

Pass a Bootstrap Icons name to icon=. When text is empty the icon displays alone. Use icon_position= to control placement when both are present.

bs.Label("Home",     icon="house")
bs.Label("Settings", icon="gear",      icon_position="right")
bs.Label("Alert",    icon="exclamation-triangle", accent="warning")

# Icon-only — auto-detected when text is empty
bs.Label(icon="heart-fill", accent="danger")

Text wrapping

Set wrap_width= (in pixels) to enable multi-line wrapping.

bs.Label(
    "A longer label that wraps automatically once it exceeds the "
    "specified pixel width.",
    wrap_width=400,
    accent="secondary",
)

Reactive text

Bind a Signal[str] to textsignal= so the label updates automatically.

count      = bs.Signal(0)
count_text = bs.Signal("Count: 0")
count.subscribe(lambda v: count_text.set(f"Count: {v}"))

bs.Label(textsignal=count_text, font="heading-md", accent="primary")
bs.Button("+1", on_click=lambda: count.set(count() + 1))

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 Label lives on the Widgets API page. At a glance:

Label

Static text display with optional icon, semantic styling, and font tokens.

Full Example

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

    # Font tokens
    bs.Label("Font Tokens", font="heading-sm")
    with bs.VStack(gap=4):
        for token in ("heading-xl", "heading-lg", "heading-md", "heading-sm",
                      "body-lg", "body", "body-sm", "caption", "code"):
            bs.Label(token, font=token)

    # Font modifiers
    bs.Label("Font Modifiers", font="heading-sm")
    with bs.HStack(gap=16):
        bs.Label("Bold",        font="body[bold]")
        bs.Label("Italic",      font="body[italic]")
        bs.Label("Bold Italic", font="body[bold][italic]")
        bs.Label("Underline",   font="body[underline]")

    # Accent colors
    bs.Label("Accent Colors", font="heading-sm")
    with bs.HStack(gap=16):
        for accent in ("primary", "secondary", "info", "success", "warning", "danger"):
            bs.Label(accent.title(), accent=accent, font="body[bold]")

    # Icons
    bs.Label("With Icons", font="heading-sm")
    with bs.HStack(gap=16):
        bs.Label("Home",    icon="house")
        bs.Label("Right",   icon="gear",                 icon_position="right")
        bs.Label("Warning", icon="exclamation-triangle", accent="warning")
        bs.Label(icon="heart-fill", accent="danger")

    # Text wrapping
    bs.Label("Text Wrapping", font="heading-sm")
    bs.Label(
        "This label wraps automatically once it exceeds the specified "
        "wrap_width in pixels. Useful for descriptive text and help copy.",
        wrap_width=400,
        accent="secondary",
    )

    # Reactive text
    bs.Label("Reactive Text", font="heading-sm")
    with bs.HStack(gap=12, anchor_items="center"):
        count      = bs.Signal(0)
        count_text = bs.Signal("Count: 0")
        count.subscribe(lambda v: count_text.set(f"Count: {v}"))
        bs.Label(textsignal=count_text, font="heading-md", accent="primary")
        bs.Button("+1", accent="primary",
                  on_click=lambda: count.set(count() + 1))

app.run()