Input

A themed single-line text field. It is controlled: it shows value and reports every keystroke to on_input, so you store the text in your state and pass it back in view(). on_submit runs on Enter.

ui.input · Category: Forms · Full reference →

Preview
Code

pz.column([
    ui.input("", on_input, placeholder="Project name"),
    ui.input("ada@example.com", on_input, icon="mail"),
    ui.input("hunter2", on_input, secure=True, icon="lock"),
], spacing=10, width=360)

Inputs with validation: the email is checked as you type.

When to use

For names, paths, search boxes, emails and passwords (secure=True).
For multi-line text or code use Editor.
Give it an id to focus it from code with pz.Command.focus(id).

Usage

import pyzed as pz
from pyzed import ui

class Form(pz.App):
    def __init__(self):
        self.name = ""

    def view(self):
        return ui.input(self.name, lambda text: setattr(self, "name", text),
                        placeholder="Project name", on_submit=self.create, id="name")

    def on_start(self):
        return pz.Command.focus("name")

Variants

Content

Size

Style

Input: borderless=True — `borderless=True`

Input: Read-only (no on_input) — Read-only (no on_input)

Validation

Show errors with Field’s error=, next to the input.

States and events

Focus, blur and keys come from the common events: .on(focus=..., blur=..., key_down=...).

Input: align="center" — `align="center"`

The pz.* widget underneath: no theme, every color and size is yours.

Events

Input has 3 events 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_input`	`ui.input`, `pz.text_input`	`(text)`	Callable that receives the new text on every keystroke.
`on_submit`	`ui.input`, `pz.text_input`	`()`	Message or callable sent when Enter is pressed.
`on_clear`	`ui.input`	`()`	Shows an ✕ while there is text; sent when it is clicked.

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.

class SignUp(pz.App):
    def __init__(self):
        self.email = ""
        self.sent = False

    def set_email(self, text):           # on_input: the new text on every keystroke
        self.email, self.sent = text, False

    def send(self):                      # on_submit: Enter
        self.sent = "@" in self.email

    def view(self):
        return pz.column([
            ui.input(self.email, self.set_email, placeholder="Email", icon="mail", id="email",
                     on_submit=self.send, on_clear=lambda: self.set_email(""),
                     invalid=bool(self.email) and "@" not in self.email),
            ui.label("Thanks!" if self.sent else "Press Enter to send"),
        ], spacing=8, width=320)

    def on_start(self):
        return pz.Command.focus("email")

from dataclasses import dataclass


@dataclass
class Typed:
    text: str


class SignUp(pz.App):
    email = ""
    sent = False

    def update(self, message):
        match message:
            case Typed(text):
                self.email, self.sent = text, False
            case "send":
                self.sent = "@" in self.email
            case "clear":
                self.email = ""

    def view(self):
        return ui.input(self.email, Typed, placeholder="Email", icon="mail",
                        on_submit="send", on_clear="clear")

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    email: str = ""
    sent: bool = False


def view(state, set_state):
    valid = "@" in state.email
    return pz.column([
        ui.input(state.email, lambda text: set_state(email=text, sent=False), placeholder="Email",
                 on_submit=lambda: set_state(sent=valid), invalid=bool(state.email) and not valid),
        ui.label("Thanks!" if state.sent else "Press Enter to send"),
    ], spacing=8, width=320)

Properties and API

`ui.input`

input(
    value,
    on_input=None,
    *,
    placeholder='',
    icon=None,
    on_submit=None,
    on_clear=None,
    id=None,
    size='md',
    secure=False,
    width='fill',
    borderless=False,
    mono=False,
    disabled=False,
    readonly=False,
    invalid=False,
    max_length=None,
    align='start',
    theme=None,
)

A text field. Focus, blur and keys come from the common events: .on(focus=..., blur=..., key_down=...).

Property	Default	Description
`value`	required	Current text.
`placeholder`	`""`	Hint text shown when empty.
`icon`	`None`	Name of a Lucide icon (`pyzed icons` lists them).
`id`	`None`	Stable identifier used to focus or scroll it with a `Command`.
`size`	`"md"`	`"sm"`, `"md"` or `"lg"`.
`secure`	`False`	Hides the text.
`width`	`"fill"`	Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion).
`borderless`	`False`	No border or background (as in the command palette).
`mono`	`False`	Uses the monospace font (IBM Plex Mono).
`disabled`	`False`	Greys it out and ignores typing.
`readonly`	`False`	Selectable and copyable, but it can’t be changed.
`invalid`	`False`	Paints the border in the error color.
`max_length`	`None`	Ignores edits longer than this.
`align`	`"start"`	Text alignment: `"start"`, `"center"` or `"end"`.
`theme`	`None`	Theme to use instead of the current one (`pyzed.theme.current()`).

Events: on_input, on_submit, on_clear (events).

Full reference →

`pz.text_input`

text_input(
    value,
    *,
    placeholder='',
    on_input=None,
    on_submit=None,
    id=None,
    size=None,
    font=None,
    padding=None,
    width=None,
    secure=False,
    icon=None,
    icon_size=None,
    bg=None,
    border_color=None,
    hover_border_color=None,
    focus_border_color=None,
    border_width=None,
    radius=None,
    color=None,
    placeholder_color=None,
    selection_color=None,
    icon_color=None,
    align_x=None,
)

A controlled text field: it shows value and notifies you of changes through on_input. For the themed field use ui.input.

Property	Default	Description
`value`	required	Current text.
`placeholder`	`""`	Hint text shown when empty.
`id`	`None`	Stable identifier used to focus or scroll it with a `Command`.
`size`	`None`	Font size.
`font`	`None`	Font family.
`padding`	`None`	Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`.
`width`	`None`	Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion).
`secure`	`False`	Hides the text (passwords).
`icon`	`None`	Icon character (use `pyzed.icons.glyph(name)`).
`icon_size`	`None`	Icon size.
`bg`	`None`	Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`).
`border_color`	`None`	Border color.
`hover_border_color`	`None`	Border color on hover.
`focus_border_color`	`None`	Border color when focused.
`border_width`	`None`	Border width in pixels.
`radius`	`None`	Corner radius: a number or `(top_left, top_right, bottom_right, bottom_left)`.
`color`	`None`	Text or icon color.
`placeholder_color`	`None`	Placeholder color.
`selection_color`	`None`	Selection color.
`icon_color`	`None`	Icon color.
`align_x`	`None`	Horizontal alignment: `"start"`/`"left"`, `"center"`, `"end"`/`"right"`.

Events: on_input, on_submit (events).