Form

bs.Form builds a data-entry layout from a dict or an explicit list of field definitions. Fields are placed on a grid; GroupItem creates labeled sections and TabsItem creates a tabbed layout.

Usage

A Form turns a dict (or a list of field definitions) into a laid-out, validating data-entry surface — fields map to the right widget by value type, form.values reads them all back, and form.valid tracks validity reactively. Embed it in a page, or use a FormDialog for a modal.

Auto-generated fields

Pass a dict to data=. Keys become field labels; value types determine the editor widget automatically:

bs.Form(
    data={
        "name": "Alice Smith",     # str  → text entry
        "email": "alice@example.com",
        "age": 30,                 # int  → numeric entry
        "active": True,            # bool → checkbox
    },
)

The returned value dict has the same keys as data, filled with the user’s current input.

Multiple columns

Use col_count= to distribute fields across multiple columns:

bs.Form(
    data={
        "street": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip": "62701",
    },
    col_count=2,
)

Explicit fields

Use FieldItem for full control over each field — label, type hint, editor, and grid placement:

bs.Form(
    items=[
        bs.FieldItem(key="username", label="Username"),
        bs.FieldItem(key="password", label="Password", dtype="password"),
        bs.FieldItem(key="role", label="Role",
                     editor="select",
                     editor_options={"values": ["Admin", "Editor", "Viewer"]}),
    ],
)

Editor types

The editor= argument on FieldItem forces a specific widget regardless of the field’s value type. Editor names match the corresponding bs.* widget class name in lowercase:

Editor	Public widget	Notes
'textfield'	TextField	Single-line text input. Default for str.
'numberfield'	NumberField	Numeric input with stepper buttons. Default for int / float.
'passwordfield'	PasswordField	Masked text input. Default for dtype='password'.
'datefield'	DateField	Date picker with calendar popup. Default for date / datetime.
'textarea'	TextArea	Multi-line text editor.
'select'	Select	Drop-down list. Requires editor_options={"values": [...]}. Pass editor_options={"allow_custom_values": True} for an editable combobox.
'spinnerfield'	SpinnerField	Numeric spinner field.
'checkbox'	Checkbox	Checkbox control. Default for bool.
'switch'	Switch	Toggle switch.
'slider'	Slider	Horizontal slider.

Editor options

editor_options are the keyword arguments of the editor’s public widget — the same names you would pass when constructing that bs.* widget directly. For a numberfield that means NumberField options such as step and min_value; for a textarea it means TextArea options such as show_border:

bs.Form(
    items=[
        bs.FieldItem(key="quantity", label="Quantity", editor="numberfield",
                     editor_options={"step": 10, "min_value": 0}),
        bs.FieldItem(key="notes", label="Notes", editor="textarea",
                     editor_options={"height": 5, "show_border": True}),
    ],
)

An option that names something the form also fills — such as label, or a select’s choices — overrides the form’s own default. Two behave differently: value seeds the editor only when the form’s data carries nothing for that key, so your record always wins; and parent is owned by the form, which places every editor in its own field container.

Grouped fields

Use GroupItem to create a labeled section with its own column layout:

bs.Form(
    items=[
        bs.GroupItem(
            label="Contact",
            col_count=2,
            items=[
                bs.FieldItem(key="first_name", label="First Name"),
                bs.FieldItem(key="last_name",  label="Last Name"),
                bs.FieldItem(key="email",      label="Email"),
                bs.FieldItem(key="phone",      label="Phone"),
            ],
        ),
    ],
)

Groups can be nested and placed in specific grid cells using column=, row=, and columnspan=.

Tabbed layouts

Use TabsItem with TabItem to organize fields into tabs:

bs.Form(
    items=[
        bs.TabsItem(tabs=[
            bs.TabItem(
                label="Account",
                items=[
                    bs.FieldItem(key="username", label="Username"),
                    bs.FieldItem(key="password", label="Password", dtype="password"),
                ],
            ),
            bs.TabItem(
                label="Profile",
                items=[
                    bs.FieldItem(key="bio",     label="Bio",     editor="textarea"),
                    bs.FieldItem(key="website", label="Website"),
                ],
            ),
        ]),
    ],
)

Validation

Call validate() to run validation rules on all fields. Access individual field widgets via field(key) to attach rules:

form = bs.Form(data={"email": "", "username": ""})

form.field("email").add_validation_rule(
    "email", message="Enter a valid email address.", trigger="blur"
)
form.field("username").add_validation_rule(
    "stringLength", min=3, message="At least 3 characters.", trigger="blur"
)

if form.validate():
    submit(form.value)

Reactive updates

Use on_data_change= at construction time, or call on_data_change() after construction. Both receive the current form data as a dict:

# constructor kwarg
bs.Form(
    data={"title": "", "description": ""},
    on_data_change=lambda data: preview(data),
)

# event shorthand — returns a Subscription
form = bs.Form(data={"title": "", "description": ""})
form.on_data_change(lambda data: preview(data))

# composable Stream
form.on_data_change().debounce(300).listen(lambda data: preview(data))

Footer buttons

Pass buttons= to add a button row below the fields. Each button can be a plain string, a DialogButton instance, or a dict with text, role, and result keys. When clicked, form.result is set to that button’s result value:

form = bs.Form(
    data={"name": "", "email": ""},
    buttons=[
        {"text": "Save",   "role": "primary", "result": "save"},
        {"text": "Cancel", "role": "cancel",  "result": None},
    ],
)

# after the user clicks:
if form.result == "save":
    submit(form.value)

Button role controls the visual style: 'primary', 'secondary', 'danger', or 'cancel'. A plain string button carries no role, so it renders in the neutral default style regardless of its position in the row — give a button a role (through a dict or DialogButton) to make it primary or destructive.

Note

FormDialog uses this same mechanism internally — it wraps an embedded Form in a dialog window. Use buttons= on a standalone Form when you want an in-page form with its own action row rather than a modal popup.

Reading and writing values

form = bs.Form(data={"name": "Alice", "age": 30})

# Read all values
values = form.value        # {'name': 'Alice', 'age': 30}
values = form.get()        # equivalent

# Write values — only the keys you pass are changed
form.value = {"name": "Bob", "age": 25}
form.set({"name": "Bob", "age": 25})   # equivalent
form.set({"age": 26})                  # writes age; name is left alone

# Read / write a single field
name = form.get_field_value("name")
form.set_field_value("name", "Carol")

# Reactive access
sig = form.field_signal("age")
sig.subscribe(lambda v: print(f"age changed: {v}"))

Widget sizing

All widgets accept self-placement kwargs via **kwargs. The parent container determines which options apply — Column / Row parents use the layout kwargs below, grid-based parents use grid kwargs.

Column (vertical layout)

Used inside a Column, App, or any other container with a column layout. Children are arranged top-to-bottom, so horizontal aligns each child across the width and grow shares the vertical space. (vertical does not apply — the order of the children sets their top-to-bottom position.)

horizontal	Cross-axis placement of the widget: 'left', 'center', 'right', or 'stretch' to fill the available width.
grow	Claim and fill a share of the leftover vertical space (the layout direction). True or False.
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=.

Row (horizontal layout)

Used inside a Row or any other container with a row layout. Children are arranged left-to-right, so vertical aligns each child across the height and grow shares the horizontal space. (horizontal does not apply — the order of the children sets their left-to-right position.)

vertical	Cross-axis placement of the widget: 'top', 'center', 'bottom', or 'stretch' to fill the available height.
grow	Claim and fill a share of the leftover horizontal space (the layout direction). True or False.
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.
horizontal	Horizontal placement within the grid cell: 'left', 'center', 'right', or 'stretch' to fill the cell width.
vertical	Vertical placement within the grid cell: 'top', 'center', 'bottom', or 'stretch' to fill the cell height.
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

Form Dialog — FormDialog embeds a Form in a dialog window with built-in OK / Cancel buttons.

API

The complete reference for Form and its item types — FieldItem, GroupItem, TabsItem, TabItem, and the FormItem union — lives on the Widgets API page. At a glance:

Form	Data-entry form built from data or explicit field definitions.
FieldItem	A single field in a Form, addressed by its key.
GroupItem	A labeled group of fields with its own column layout, placed in a Form.
TabsItem	A tab container holding one or more TabItem entries, placed in a Form.
TabItem	A single tab within a TabsItem.
FormItem	Represent a PEP 604 union type

Full Example

with bs.App(title="Form Demo", minsize=(700, 780), padding=20, gap=12) as app:

    # Auto-generated fields from a data dict
    bs.Label("Auto-Generated Fields", font="heading-sm")
    bs.Form(
        data={
            "name": "Alice Smith",
            "email": "alice@example.com",
            "age": 30,
            "active": True,
        },
        horizontal="stretch",
    )

    # Multi-column layout
    bs.Label("Multiple Columns", font="heading-sm")
    bs.Form(
        data={
            "street": "123 Main St",
            "city": "Springfield",
            "state": "IL",
            "zip": "62701",
        },
        col_count=2,
        horizontal="stretch",
    )

    # Grouped fields with GroupItem
    bs.Label("Grouped Fields", font="heading-sm")
    bs.Form(
        items=[
            bs.GroupItem(
                label="Contact",
                col_count=2,
                items=[
                    bs.FieldItem(key="first_name", label="First Name"),
                    bs.FieldItem(key="last_name",  label="Last Name"),
                    bs.FieldItem(key="email",       label="Email"),
                    bs.FieldItem(key="phone",       label="Phone"),
                ],
            ),
        ],
        horizontal="stretch",
    )

    # Tabbed layout with TabsItem
    bs.Label("Tabbed Layout", font="heading-sm")
    bs.Form(
        items=[
            bs.TabsItem(tabs=[
                bs.TabItem(
                    label="Account",
                    items=[
                        bs.FieldItem(key="username", label="Username"),
                        bs.FieldItem(key="password", label="Password", dtype="password"),
                    ],
                ),
                bs.TabItem(
                    label="Profile",
                    items=[
                        bs.FieldItem(key="bio",     label="Bio",     editor="textarea"),
                        bs.FieldItem(key="website", label="Website"),
                    ],
                ),
            ]),
        ],
        horizontal="stretch",
    )

app.run()