Types

Token and keyword types for annotating your own helpers and widget subclasses. These are the names that appear in widget signatures — the accent/variant/surface tokens, the layout literals, density, and the keyword TypedDicts. Import them from bootstack.types when you annotate code that builds on bootstack:

from bootstack.types import AccentToken, WidgetDensity

Style and state tokens

Semantic tokens for color, variant, and surface, plus density, state, and the lower-level appearance literals.

type bootstack.types.AccentToken

A semantic color accent — 'primary', 'secondary', 'info', 'success', 'warning', 'danger'. Accent params widen it with | str, also accepting 'default', 'muted', and modifiers like 'primary[500]'.

type bootstack.types.AccordionVariant

Accordion header style — 'solid', or 'default' for a ghost/transparent header.

type bootstack.types.BorderMode

Border placement for the place geometry manager — 'inside' or 'outside'.

type bootstack.types.ButtonVariant

Style variant shared by the button family (Button, ButtonGroup, CommandBar, MenuButton, SelectButton, ToggleButton, ToggleGroup) — 'default', 'solid', 'outline', or 'ghost'.

type bootstack.types.CompoundMode

Position of an image relative to its text — 'text', 'image', 'top', 'bottom', 'left', 'right', 'center', 'none'.

type bootstack.types.Relief

Border relief style — 'flat', 'raised', 'sunken', 'groove', 'ridge', 'solid'.

type bootstack.types.SurfaceToken

Background surface context — 'content', 'card', 'card_raised', 'chrome', 'overlay'.

type bootstack.types.VariantToken

Widget style variant — 'solid', 'outline', 'ghost', 'toggle'.

type bootstack.types.WidgetDensity

Sizing density — 'default', or 'compact' for reduced padding.

type bootstack.types.ScrollbarVariant

Scrollbar style — 'default' for the standard rounded bar, or 'thin' for a slim square bar that suits compact lists, panels, and popups.

type bootstack.types.WidgetState

Widget interaction state — 'normal', 'active', 'disabled', 'readonly'.

type bootstack.types.WindowStyle

A Windows-only window effect (no-op elsewhere) — 'mica', 'acrylic', 'aero', 'transparent', 'win7'. The underlying pywinstyles library accepts more, passed as a plain string.

Layout literals

The placement and sizing literals accepted by container and **kwargs layout options.

type bootstack.types.Anchor

Alignment anchor position — 'n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw', 'center'.

type bootstack.types.AutoFlow

Grid auto-placement direction — 'row', 'column', 'row-dense', 'column-dense', 'none'.

type bootstack.types.Direction

Layout direction — 'vertical', 'horizontal', 'row', 'column', 'row-reverse', 'column-reverse'.

type bootstack.types.Fill

Fill axis for stack layout — 'none', 'x', 'y', 'both', with readable aliases 'horizontal', 'vertical', 'all'.

type bootstack.types.IconPosition

Position of an icon relative to a widget’s text — 'left', 'right', 'top', or 'bottom'.

type bootstack.types.Justify

Text justification within a widget — 'left', 'center', 'right'.

type bootstack.types.LayoutKind

A container’s internal layout manager — 'vstack', 'hstack', 'grid'.

type bootstack.types.Orient

Widget orientation — 'horizontal', 'vertical'.

type bootstack.types.Padding

Widget padding in pixels — a single int for all sides, (x, y) for the horizontal and vertical amounts, or (left, top, right, bottom).

type bootstack.types.Region

Placement region within a menu bar — 'before', 'center', or 'after'.

type bootstack.types.Side

Side placement for stack layout — 'left', 'top', 'right', 'bottom'.

type bootstack.types.Sticky

Cell alignment for Grid layout — any combination of 'n', 's', 'e', 'w' (e.g. 'nsew').

Data and selection

Literals for selection behavior and tabular data export.

type bootstack.types.ExportFormat

A tabular export format — 'csv', 'tsv', or 'xlsx'.

type bootstack.types.ExportScope

Which rows an export covers — 'all' rows, the current 'page', or the current 'selection'.

type bootstack.types.Option

A single choice for Select, SelectButton, RadioGroup, or ToggleGroup — a plain str (text and value are the same), a (text, value) tuple, or an OptionDict. Lets an option’s displayed label differ from its stored value.

type bootstack.types.Icon

An icon as either a Bootstrap Icons name ('bell-fill') or an IconSpec mapping for control over size and color.

type bootstack.types.SelectionMode

How many rows or items can be selected — 'none', 'single', or 'multi'.

Keyword and config types

The TypedDict shapes for low-level widget options and the data-entry config that DataTable and Form accept.

class bootstack.types.BaseWidgetKwargs

Bases: TypedDict

Low-level options shared by all bootstack widget wrappers.

class_: str

cursor: str

name: str

style: str

takefocus: bool

class bootstack.types.ColumnSpec

Bases: TypedDict

A column definition for DataTable(columns=...).

Columns may be plain key strings or these dicts. Only key is required; the editor keys (editor, editor_options, dtype, readonly, required) shape how the column appears in the built-in add/edit dialog.

anchor: str

Cell alignment — 'w', 'center', or 'e'.

dtype: str

Value type hint (e.g. 'int', 'text'); drives alignment and the editor.

editor: Literal['textfield', 'numberfield', 'passwordfield', 'datefield', 'textarea', 'select', 'spinnerfield', 'switch', 'checkbox', 'slider']

Field type used to edit this column in the add/edit dialog. Inferred from dtype when omitted.

editor_options: dict

Keyword options passed to the editor field.

format: str | Callable[[Any], str]

Display formatter for the cell — a format-spec string applied as spec.format(value) (e.g. '${:,.0f}' → $70,000) or a callable (value) -> str. Display only: sorting, filtering, editing, and export use the raw value.

key: str

Record field this column reads and writes.

minwidth: int

Minimum column width in pixels.

readonly: bool

Show the column but make it non-editable in the dialog.

required: bool

Require a value in the add/edit dialog.

text: str

Header label. Defaults to key.

width: int

Column width in pixels.

type bootstack.types.EditorType

The field type used to edit a value in a Form or DataTable add/edit dialog, inferred from the value’s dtype when omitted — 'textfield', 'numberfield', 'passwordfield', 'datefield', 'textarea', 'select', 'spinnerfield', 'switch', 'checkbox', 'slider'.

class bootstack.types.FormOptions

Bases: TypedDict

Layout options for the built-in add/edit dialog (DataTable(form=...)).

col_count: int

Number of columns the form fields are laid out in. Default 2.

min_col_width: int

Minimum width in pixels of each form column. Default 260.

resizable: bool

Allow the dialog to be resized. Default True.

scrollable: bool

Scroll the form when it is taller than the dialog. Default True.

class bootstack.types.IconSpec

Bases: TypedDict

A detailed icon specification: a Bootstrap icon name with size and color.

Use in place of a plain icon name wherever a widget accepts icon=, to control the rendered size and color — for example icon={'name': 'bell-fill', 'size': 24, 'color': 'primary'}.

color: str

Icon color — a theme color token (e.g. 'primary') or a hex string.

name: str

Bootstrap Icons name, e.g. 'bell-fill'.

size: int

Icon size in pixels (automatically DPI-scaled).

class bootstack.types.OptionDict

Bases: TypedDict

A single choice for a selection widget, in dict form.

The dict form is a data bag: text is required (and value defaults to it) UNLESS the dict carries an icon and a value, in which case text may be omitted to request an icon-only option. text/value and the recognized icon/disabled keys act on rendering; every other key rides along as carried data — retrievable as the widget’s selection (the selected option’s full record). Unrecognized keys are accepted, not rejected, so the dict route trades key-typo safety for extensibility.

disabled: bool

When True, the option is dimmed and cannot be selected by the user.

icon: str

Optional icon spec rendered beside the label — alone when text is blank.

localize: bool | Literal['auto']

Per-option translation mode — True, False, or 'auto'. Overrides the widget’s group-level localize= for just this option. Set False to keep a proper noun or identifier untranslated.

text: str

Display label. Required unless icon + value are given (icon-only).

value: Any

Stored and emitted value. Defaults to text when omitted.

class bootstack.types.StyledKwargs

Bases: BaseWidgetKwargs

Extends BaseWidgetKwargs with bootstack styling tokens.

accent: Literal['primary', 'secondary', 'info', 'success', 'warning', 'danger'] | str

class_: str

cursor: str

name: str

style: str

style_options: dict[str, Any]

surface: Literal['content', 'card', 'card_raised', 'chrome', 'overlay'] | str

takefocus: bool

variant: Literal['solid', 'outline', 'ghost', 'toggle'] | str