PathField

A text field with a browse button that opens a native file or directory picker dialog. When the user confirms a selection, the field value is updated and a change event fires.

Usage

Basic usage

bs.PathField(placeholder="Select a file…")

Dialog modes

Use mode= to control which native dialog opens when the browse button is clicked. The default is 'open'.

bs.PathField(mode="open")           # single-file open
bs.PathField(mode="open_multiple")  # multi-file open (result is a tuple)
bs.PathField(mode="save")           # save-file dialog
bs.PathField(mode="directory")      # directory picker

File filters

Pass file_filters= as a list of (description, pattern) pairs to restrict which file types appear in the dialog. Has no effect in 'directory' mode.

bs.PathField(
    file_filters=[
        ("Images", "*.png *.jpg *.jpeg *.gif"),
        ("All Files", "*.*"),
    ],
)

Label and message

Use label= for a field title and message= for helper text below. Set required=True to mark the field visually.

bs.PathField(
    label="Output directory",
    message="Folder must be writable.",
    mode="directory",
    required=True,
)

States

bs.PathField(value="/home/user/docs/report.pdf", label="Normal")
bs.PathField(value="/home/user/docs/report.pdf", label="Read only", read_only=True)
bs.PathField(value="/home/user/docs/report.pdf", label="Disabled",  disabled=True)

Reactive binding

Bind a Signal[str] with textsignal=. The field and signal stay in sync automatically.

path = bs.Signal("")
bs.PathField(label="Pick a file", textsignal=path)
bs.Label(textsignal=path, accent="secondary")   # updates on each selection

Handling changes

Use on_change() to respond when the user picks a path. The event fires after the dialog closes and the value is committed, or when the user edits the text portion directly and leaves the field.

pf = bs.PathField(label="Source file")

def handle_change(e):
    print("Selected:", pf.value)

pf.on_change(handle_change)

# As a subscription (cancellable)
sub = pf.on_change(handle_change)
sub.cancel()

# As a Stream (composable)
pf.on_change().listen(handle_change)

For 'open_multiple' mode, the raw tuple of paths is available on pf.dialog_result after the dialog closes.

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 single-line text input

• NumberField — numeric-only input with stepper

API

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

PathField

A text field with a browse button that opens a native file/directory dialog.

Full Example

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

    # Basic usage
    bs.Label("Basic", font="heading-sm")
    bs.PathField(placeholder="Select a file…")

    # Dialog modes
    bs.Label("Dialog Modes", font="heading-sm")
    bs.PathField(label="Open file",        mode="open",          placeholder="Select a file…")
    bs.PathField(label="Open multiple",    mode="open_multiple", placeholder="Select files…")
    bs.PathField(label="Save file",        mode="save",          placeholder="Choose save location…")
    bs.PathField(label="Select directory", mode="directory",     placeholder="Select a folder…")

    # File filters
    bs.Label("File Filters", font="heading-sm")
    bs.PathField(
        label="Image file",
        file_filters=[("Images", "*.png *.jpg *.jpeg *.gif"), ("All Files", "*.*")],
        placeholder="Select an image…",
    )

    # Label and message
    bs.Label("Label and Message", font="heading-sm")
    bs.PathField(
        label="Project folder",
        message="Must contain a pyproject.toml or setup.py.",
        placeholder="Select a folder…",
        mode="directory",
        required=True,
    )

    # Reactive binding
    bs.Label("Reactive Binding", font="heading-sm")
    path_sig = bs.Signal("")
    bs.PathField(label="Pick a file", textsignal=path_sig)
    bs.Label(textsignal=path_sig, accent="secondary")

    # States
    bs.Label("States", font="heading-sm")
    bs.PathField(value="/home/user/docs/report.pdf", label="Normal")
    bs.PathField(value="/home/user/docs/report.pdf", label="Read only", read_only=True)
    bs.PathField(value="/home/user/docs/report.pdf", label="Disabled",  disabled=True)

    # Handling changes
    bs.Label("Handling Changes", font="heading-sm")
    last = bs.Signal("(none)")
    pf = bs.PathField(label="Choose a file")
    pf.on_change(lambda e: last.set(pf.value))
    bs.Label(textsignal=last, accent="secondary")

app.run()