TextField

Single-line text input with optional label, helper text, placeholder, validation, and reactive signal binding.

Usage

Basic

bs.TextField(placeholder="Type something…")

Label and message

Use label= for a field title and message= for helper text below.

bs.TextField(
    label="Email address",
    placeholder="you@example.com",
    message="We'll never share your email.",
)

Required

Set required=True to mark the field visually and prevent empty submission.

bs.TextField(label="Username",     required=True, placeholder="Required field")
bs.TextField(label="Email address", placeholder="Optional field")

Value formatting

Use value_format= to display the value with a locale-aware ICU pattern. The raw string value is preserved internally; only the display changes. Requires localization to be enabled.

bs.TextField(value_format="#,##0.00", label="Decimal")
bs.TextField(value_format="percent",  label="Percent")
bs.TextField(value_format="currency", label="Currency")
bs.TextField(value_format="yyyy-MM-dd", label="Date")

States

bs.TextField(value="Editable",  label="Normal")
bs.TextField(value="Read only", label="Read only", read_only=True)
bs.TextField(value="Disabled",  label="Disabled",  disabled=True)

Reactive binding

Bind a Signal[str] with textsignal=. The field and signal stay in sync automatically — typing updates the signal, setting the signal updates the field.

name = bs.Signal("World")
bs.TextField(label="Name", textsignal=name)
bs.Label(textsignal=name, accent="secondary")   # updates as you type

Live input events

on_input() fires on every keystroke. Use it for real-time feedback, character counting, or live search — anything that needs to respond to typing, not just field exit.

count = bs.Label("0 / 100", accent="secondary", font="caption")
field = bs.TextField(placeholder="Type…")

def _update_count(e):
    count.text = f"{len(field.value)} / 100"

field.on_input(_update_count)

# Or as a debounced Stream
field.on_input().debounce(300).listen(lambda e: search(field.value))

Submit on Enter

field = bs.TextField(placeholder="Search…")
field.on_submit(lambda e: run_search(field.value))

Validation

Attach rules with add_validation_rule(). Rules run on the configured trigger ('blur', 'key', or 'manual').

field = bs.TextField(label="Username")
field.add_validation_rule(
    "stringLength",
    message="Must be at least 3 characters.",
    min=3,
    trigger="blur",
)

# Explicit validation check
is_valid = field.validate()

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

TextField

Single-line text input with optional label, message, and validation.

Full Example

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

    # Basic
    bs.Label("Basic", font="heading-sm")
    basic = bs.TextField(value="Hello, bootstack!", fill="x")

    # Label and message
    bs.Label("Label and Message", font="heading-sm")
    bs.TextField(
        label="Email address",
        placeholder="you@example.com",
        message="We'll never share your email.",
        fill="x",
    )

    # Required
    bs.Label("Required", font="heading-sm")
    bs.TextField(label="Username", placeholder="Choose a username", required=True, fill="x")

    # States
    bs.Label("States", font="heading-sm")
    with bs.HStack(gap=8, fill="x", fill_items="x", expand_items=True):
        bs.TextField(value="Editable",  label="Normal")
        bs.TextField(value="Read only", label="Read only", read_only=True)
        bs.TextField(value="Disabled",  label="Disabled", disabled=True)

    # Reactive binding
    bs.Label("Reactive Binding", font="heading-sm")
    with bs.VStack(gap=6, fill="x"):
        name = bs.Signal("bootstack")
        bs.TextField(label="Name", textsignal=name, fill="x")
        bs.Label(textsignal=name, accent="secondary", font="caption")

    # Live character count via on_input
    bs.Label("Live Character Count (on_input)", font="heading-sm")
    with bs.VStack(gap=4, fill="x"):
        count_lbl = bs.Label("0 / 50", accent="secondary", font="caption")
        field = bs.TextField(placeholder="Type to count…", fill="x")

        def _update_count(e):
            count_lbl.text = f"{len(field.value)} / 50"

        field.on_input(_update_count)

    # on_submit
    bs.Label("Submit on Enter (on_submit)", font="heading-sm")
    with bs.VStack(gap=4, fill="x"):
        result_lbl = bs.Label("", accent="success", font="caption")
        submit_field = bs.TextField(placeholder="Type and press Enter…", fill="x")
        def _on_submit(e):
            result_lbl.text = f"Submitted: {submit_field.value}"

        submit_field.on_submit(_on_submit)

    # Validation
    bs.Label("Validation", font="heading-sm")
    from bootstack.validation import ValidationRule
    vf = bs.TextField(label="Min 3 characters", placeholder="Enter text…", fill="x")
    vf.add_validation_rule(ValidationRule(
        "stringLength",
        message="Must be at least 3 characters.",
        min=3,
        trigger="blur",
    ))

app.run()