GroupBox

A labelled container that groups related content inside a bordered frame. The title is embedded in the top border line, giving the classic fieldset look familiar from HTML <fieldset> and desktop dialog panels.

Usage

Accent borders

Pass an accent= token to color the border and title label. The title text automatically inherits the accent color.

with bs.GroupBox("Primary", accent="primary", padding=20, gap=16):
    bs.Label("Item one")
    bs.Label("Item two")

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.GroupBox("Details", gap=8):
    bs.Label("First")
    bs.Label("Second")

# Horizontal stack
with bs.GroupBox("Steps", layout="hstack", gap=12, anchor_items="center"):
    bs.Label("A")
    bs.Label("B")
    bs.Label("C")

# Grid — two columns, key/value pairs
with bs.GroupBox("Info", layout="grid", columns=[1, 1], gap=8, sticky_items="ew"):
    bs.Label("Name:")  ; bs.Label("Ada Lovelace")
    bs.Label("Role:")  ; bs.Label("Engineer")

Child defaults

Use fill_items, expand_items, and anchor_items to apply a uniform layout behavior to all children without repeating it on each widget.

with bs.GroupBox("Filters", gap=8, fill_items="x"):
    bs.TextField()   # fills horizontally by default
    bs.TextField()

In context

GroupBox is commonly used to visually separate settings panels or summary sections within a larger form or dashboard.

with bs.GroupBox("Connection", accent="primary", padding=12, gap=8):
    with bs.HStack(gap=8):
        bs.Label("Host:")
        bs.Label("localhost")
    with bs.HStack(gap=8):
        bs.Label("Status:")
        bs.Label("Connected", accent="success")

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

See also

VStack, HStack, and Grid are the plain (no border) layout containers. Use GroupBox when you want a labelled border around a group of related content.

API

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

GroupBox

A labeled container that groups related content inside a bordered frame.

Full Example

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

    # Accent borders
    bs.Label("Accent Borders", font="heading-sm")
    with bs.HStack(gap=12, anchor_items="n"):
        for accent in ("default", "primary", "secondary", "success", "warning", "danger"):
            with bs.GroupBox(accent.title(), accent=accent, padding=10, gap=4):
                bs.Label("Item one")
                bs.Label("Item two")

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

        with bs.GroupBox("VStack (default)", padding=10, gap=8):
            bs.Label("First")
            bs.Label("Second")
            bs.Label("Third")

        with bs.GroupBox("HStack", layout="hstack", padding=10, gap=12, anchor_items="center"):
            bs.Label("A")
            bs.Label("B")
            bs.Label("C")

        with bs.GroupBox("Grid", layout="grid", columns=[1, 1], padding=10, gap=8, sticky_items="ew"):
            bs.Label("Name:")
            bs.Label("Ada Lovelace")
            bs.Label("Role:")
            bs.Label("Engineer")

    # In context
    bs.Label("In Context", font="heading-sm")
    with bs.HStack(gap=12, anchor_items="n"):

        with bs.GroupBox("Connection", accent="primary", padding=12, gap=8):
            with bs.HStack(gap=8, anchor_items="center"):
                bs.Label("Host:")
                bs.Label("localhost")
            with bs.HStack(gap=8, anchor_items="center"):
                bs.Label("Port:")
                bs.Label("5432")
            with bs.HStack(gap=8, anchor_items="center"):
                bs.Label("Status:")
                bs.Label("Connected", accent="success")

        with bs.GroupBox("Alerts", accent="warning", padding=12, gap=6):
            bs.Label("Disk usage above 80%", accent="warning")
            bs.Label("2 services degraded", accent="danger")
            bs.Label("Backup completed", accent="success")

app.run()