PasswordField

Masked text input for password entry with an optional visibility toggle.

Usage

Basic

bs.PasswordField(placeholder="Enter password…")

Label and message

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

bs.PasswordField(
    label="Password",
    placeholder="Enter password…",
    message="Must be at least 8 characters.",
)

Required

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

bs.PasswordField(label="Password", required=True)

Visibility toggle

The eye-icon button is shown by default and reveals the password while held. Disable it with show_visibility_toggle=False.

bs.PasswordField(label="With toggle", value="secret123")
bs.PasswordField(label="No toggle",   value="secret123", show_visibility_toggle=False)

Programmatic reveal / hide

Call reveal() and hide() to control masking in code — useful for a “show password” checkbox pattern.

field = bs.PasswordField(label="Password", show_visibility_toggle=False)

def _toggle_reveal(e):
    if checkbox.value:
        field.reveal()
    else:
        field.hide()

checkbox = bs.Checkbox("Show password", on_change=_toggle_reveal)

Custom mask character

The default mask is '•'. Supply any single character via mask=.

bs.PasswordField(mask="*")

States

bs.PasswordField(value="secret123", label="Normal")
bs.PasswordField(value="secret123", label="Read only", read_only=True)
bs.PasswordField(value="secret123", 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.

password = bs.Signal("")
bs.PasswordField(label="Password", textsignal=password)
password.subscribe(lambda v: validate_strength(v))

Submit on Enter

field = bs.PasswordField(placeholder="Password…")
field.on_submit(lambda e: attempt_login(field.value))

Validation

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

field = bs.PasswordField(label="Password")
field.add_validation_rule(
    "stringLength",
    message="Password must be at least 8 characters.",
    min=8,
    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).

See also

• TextField — plain text input

• NumberField — numeric input with optional range constraints

API

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

PasswordField

A masked text field for password input with an optional visibility toggle.

Full Example

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

    # Basic
    bs.Label("Basic", font="heading-sm")
    bs.PasswordField(placeholder="Enter password…", fill="x")

    # Label, message, required
    bs.Label("Label, Message, Required", font="heading-sm")
    bs.PasswordField(
        label="Password",
        placeholder="Enter password…",
        message="Must be at least 8 characters.",
        required=True,
        fill="x",
    )

    # Visibility toggle
    bs.Label("Visibility Toggle", font="heading-sm")
    with bs.HStack(gap=8, fill="x", fill_items="x", expand_items=True):
        bs.PasswordField(label="With toggle", value="secret123")
        bs.PasswordField(label="No toggle",   value="secret123", show_visibility_toggle=False)

    # Custom mask character
    bs.Label("Custom Mask Character", font="heading-sm")
    with bs.HStack(gap=8, fill="x", fill_items="x", expand_items=True):
        bs.PasswordField(value="secret", label="Default (•)")
        bs.PasswordField(value="secret", label="Asterisk (*)", mask="*")

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

app.run()