Search input

In plain words

A text box with a magnifying glass, for typing what you are looking for.

An input with a magnifying glass icon and "Search…" as placeholder. It accepts every other parameter of ui.input.

ui.search_input · Category: Forms · Full reference →

Preview

Code

pz.column([
    ui.search_input("", on_query),
    ui.search_input("button", on_query, placeholder="Search components…"),
], spacing=10, width=360)

When to use

• At the top of a list, tree or table to filter it as you type.
• Pair it with ui.fuzzy_filter to rank the best matches first.

Usage

import pyzed as pz
from pyzed import ui

class Finder(pz.App):
    def __init__(self):
        self.query = ""
        self.files = ["main.py", "app.py", "theme.py"]

    def view(self):
        matches = ui.fuzzy_filter(self.query, self.files)
        return pz.column([
            ui.search_input(self.query, lambda q: setattr(self, "query", q)),
            *[ui.list_item(name, icon="file") for name, _ in matches],
        ], spacing=6)

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.

Content

Empty

Code

ui.search_input("", on_query, width=260)

With a query

Code

ui.search_input("button", on_query, width=260)

placeholder=

Code

ui.search_input("", on_query, placeholder="Search components…", width=260)

Size

size="sm"

Code

ui.search_input("", on_query, size="sm", width=260)

size="lg"

Code

ui.search_input("", on_query, size="lg", width=260)

borderless=True

Code

ui.search_input("", on_query, borderless=True, width=260)

Events

Search input 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	Handler gets	When
on_input	(text)	Callable that receives the new text on every keystroke.

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 Finder(pz.App):
    def __init__(self):
        self.query = ""
        self.files = ["main.py", "app.py", "theme.py"]

    def search(self, text):              # on_input: every keystroke
        self.query = text

    def view(self):
        matches = ui.fuzzy_filter(self.query, self.files)
        return pz.column([ui.search_input(self.query, self.search),
                          *[ui.list_item(name, icon="file") for name, _ in matches]], spacing=6)

Declarative

from dataclasses import dataclass


@dataclass
class Search:
    query: str


class Finder(pz.App):
    query = ""
    files = ["main.py", "app.py", "theme.py"]

    def update(self, message):
        match message:
            case Search(query):
                self.query = query

    def view(self):
        matches = ui.fuzzy_filter(self.query, self.files)
        return pz.column([ui.search_input(self.query, Search),
                          *[ui.list_item(name, icon="file") for name, _ in matches]], spacing=6)

Functional

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    query: str = ""
    files: tuple = ("main.py", "app.py", "theme.py")


def view(state, set_state):
    matches = ui.fuzzy_filter(state.query, list(state.files))
    return pz.column([ui.search_input(state.query, lambda q: set_state(query=q)),
                      *[ui.list_item(name, icon="file") for name, _ in matches]], spacing=6)

Properties and API

ui.search_input

search_input(value, on_input=None, *, placeholder='Search…', **kwargs)

An input with a magnifying glass icon.

Property	Default	Description
value	required	Current text.
placeholder	"Search…"	Hint text shown when empty.
**kwargs	—	Same as input.

Events: on_input (events).

Full reference →

Related

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

PickerA searchable list on a floating surface, with fuzzy matching.

Command paletteA command palette with fuzzy search and shortcuts.