File picker

In plain words

A box with the location of a file and a button that opens the usual window to look for it.

ui.file_input shows a path and a browse button. The button opens the operating system’s own dialog to open a file (mode="open"), several ("open_many"), a folder ("folder") or to choose where to save ("save"), and on_change receives what the user chose: a path, or a list of paths with open_many. The path can also be typed or pasted. filters limits the file types ("Images: png, jpg").

ui.file_input · Category: System · Full reference →

Preview

Code

pz.column([
    ui.field("Project folder", ui.file_input("~/projects/notes", on_change, mode="folder")),
    ui.field("Logo", ui.file_input("", on_change, filters="Images: png, jpg, svg", placeholder="Choose an image")),
    ui.field("Export to", ui.file_input("report.pdf", on_change, mode="save", button="Browse…")),
], spacing=12, width=420)

New

This component was added recently. Tell us how it works for you in the issue tracker.

When to use

• For settings that point to a file or folder: a project folder, a log file, an export target.
• button="Browse…" shows text instead of the folder icon.
• ui.system.pick(then, mode=...) returns the same dialog as a Command, for your own buttons.

Usage

import pyzed as pz
from pyzed import ui

class Export(pz.App):
    def __init__(self):
        self.target = ""

    def view(self):
        return ui.file_input(self.target, lambda path: setattr(self, "target", path),
                             mode="save", file_name="report.pdf", filters="PDF: pdf")

Variants

About these captures

Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site’s theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open Code under a capture to see the snippet that draws it; free names such as on_save stand for your own callbacks.

Mode

mode="open"

Code

ui.file_input("~/notes/todo.md", on_change, width=320)

mode="open_many"

Code

ui.file_input(["a.png", "b.png"], on_change, mode="open_many", width=320)

mode="folder"

Code

ui.file_input("~/projects", on_change, mode="folder", width=320)

mode="save"

Code

ui.file_input("report.pdf", on_change, mode="save", width=320)

States

button="Browse…"

Code

ui.file_input("", on_change, button="Browse…", width=320)

editable=False

Code

ui.file_input("~/notes/todo.md", on_change, editable=False, width=320)

invalid=True

Code

ui.file_input("~/missing.txt", on_change, invalid=True, width=320)

disabled=True

Code

ui.file_input("~/notes/todo.md", on_change, disabled=True, width=320)

Events

File picker has 1 event of its own, listed below. Like every widget it also has the 18 common events (click, double_click, right_click, mouse_enter, drag, key_down, resize…), attached with .on(...): see Events and Events of every component.

Event	Of	Handler gets	When
on_change	ui.file_input, ui.path_input	(value)	Receives the path (a list with "open_many").

Handler gets is what Pyzed passes to your callable: () means nothing. Any handler can also be a message (a value that is not callable), which goes to update().

Handling the events

The same events written three ways. Imperative: methods of the app change self. Declarative: the handlers produce messages and one update() decides. Functional: a pure function draws an immutable state and asks for changes with set_state(...). See Imperative, declarative and functional.

Imperative

class Export(pz.App):
    def __init__(self):
        self.folder = ""

    def chosen(self, path):              # on_change: the path (a list with mode="open_many")
        self.folder = path

    def view(self):
        return pz.column([
            ui.file_input(self.folder, self.chosen, mode="folder", placeholder="Choose a folder"),
            ui.label(f"Saving to {self.folder or '…'}"),
        ], spacing=8, width=360)

Declarative

from dataclasses import dataclass


@dataclass
class Chosen:
    path: str


class Export(pz.App):
    path = ""

    def update(self, message):
        match message:
            case Chosen(path):
                self.path = path

    def view(self):
        return ui.file_input(self.path, lambda path: Chosen(path), mode="save", file_name="report.pdf")

Functional

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    image: str = ""


def view(state, set_state):
    return ui.file_input(state.image, lambda path: set_state(image=path), filters="Images: png, jpg")

Properties and API

ui.file_input

file_input(
    value,
    on_change=None,
    *,
    mode='open',
    filters=None,
    title=None,
    directory=None,
    file_name='',
    placeholder=None,
    button=None,
    editable=True,
    disabled=False,
    invalid=False,
    id=None,
    width='fill',
    theme=None,
)

A path field with a button that opens the system’s file dialog, so nobody types a path by hand. See the File picker page.

Property	Default	Description
value	required	Current value.
mode	"open"	"open" (a file), "open_many" (a list), "save" or "folder".
filters	None	Files shown: {"Images": "png jpg"} or "Images: png, jpg".
title	None	The dialog’s title.
directory	None	Where the dialog opens (default: the folder of the current path).
file_name	""	The name suggested when saving.
placeholder	None	Hint text shown when empty.
button	None	Text for the button instead of a folder icon.
editable	True	False keeps the path from being typed.
disabled	False	Disables it (ignores clicks).
invalid	False	Paints the border in the error color.
id	None	Stable identifier used to focus or scroll it with a Command.
width	"fill"	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
theme	None	Theme to use instead of the current one (pyzed.theme.current()).

Events: on_change (events).

Full reference →

ui.path_input

path_input(
    value,
    on_change=None,
    *,
    folder=False,
    save=False,
    filters=None,
    kind=None,
    directory=None,
    relative_to=None,
    title=None,
    placeholder=None,
    size='md',
    mono=True,
    disabled=False,
    invalid=False,
    theme=None,
)

A text field for a file or folder path with a button that opens the system’s file dialog, so the path never has to be typed (it still can be).

Property	Default	Description
value	required	Current path.
folder	False	Picks a folder instead of a file.
save	False	Shows the “Save as” dialog.
filters	None	(name, extensions) pairs: [("Images", ["png", "jpg"])].
kind	None	Common filters by name: "image", "audio", "video", "font", "shader" or "data".
directory	None	Folder the dialog opens in (by default, the current path’s).
relative_to	None	A chosen path inside this folder is given relative to it.
title	None	Title of the dialog.
placeholder	None	Text shown while it is empty.
size	"md"	"sm", "md" or "lg".
mono	True	Monospaced text.
disabled	False	Greys it out.
invalid	False	Paints the border in the error color.
theme	None	Theme to use instead of the current one (pyzed.theme.current()).

Events: on_change (events).

Full reference →

ui.system.pick

pick(then, *, mode='open', title=None, filters=None, directory=None, file_name='')

The system’s file dialog as a Command: return it from a callback and then receives what the user chose (a path, a list of paths with "open_many", or None when they cancel). ui.file_input uses it.

Property	Default	Description
then	required	Called with the result.
mode	"open"	"open", "open_many", "save" or "folder".
title	None	The dialog’s title.
filters	None	Files shown: {"Images": "png jpg"} or "Images: png, jpg".
directory	None	Where the dialog opens.
file_name	""	The name suggested when saving.

Full reference →

Related

Drop zoneAn area that takes files dragged from the desktop or the file manager.

InputA controlled text field with icon, placeholder and password mode.

FieldA settings row: title and description left, control right.