Search Field — HeroGPUI

Usage

Live example

Rust

1use herogpui::prelude::SearchField;
2use gpui::prelude::*;
3use gpui::px;
4
5gpui::div()
6    .flex()
7    .flex_col()
8    .items_start()
9    .gap(px(12.))
10    .children(vec![
11        gpui::div()
12            .w(px(256.))
13            .flex()
14            .flex_col()
15            .child(SearchField::new(self.search_state.clone())
16                        .label("Search docs")
17                        .placeholder("Search components")
18                        .on_change(cx.listener(|this, text: &str, _, cx| {
19                            this.search_query = text.to_owned();
20                            cx.notify();
21                        }))),
22        para(
23            &if query.is_empty() {
24                "Type to search".to_owned()
25            } else {
26                format!("Query: {query}")
27            },
28            cx,
29        ),
30    ])

Expand code

Live HeroGPUI compiled to WebAssembly. Select any example without loading another WASM instance.

Anatomy

Rust types

SearchFieldInput

Search Field is assembled from these builders. The API reference lists each one.

Customization

Appearance builders and theme tokens Search Field uses.

Styling

Search Field styling
Style	Description
`Input wrapper flex_col + gap(4px)`	Root field stack and invalid description replacement; labels use 14px/20px and helper/error text use 12px/16px.
`FIELD_HEIGHT + field_radius + apply_field_chrome`	Unified 36px field shell, radius, colours and shadow match.
`direct apply_field_chrome state colours`	State colours and focus shadow switch directly rather than interpolating.
`Input row + FIELD_TEXT`	Text inset and desktop type match; browser search decorations do not exist in GPUI.
`FIELD_ICON + Input px(12px)`	Leading icon size and inset match.
`20px clear div + 12px svg + end padding`	20px clear target with 12px glyph and 8px end inset.
`FieldVariant::Secondary in apply_field_chrome`	Lower-emphasis surface treatment.
`full_width()`	Full-width root and group modifier.

API reference

Builders

Search Field builders
Builder	Type	Default	Description
`content(render)`	`AnyElement \| Fn(values: SearchFieldRenderProps) -> AnyElement`	—	Replacement content receives disabled, invalid, read-only, required, focus, value and empty state.
`full_width()`	`bool`	`false`	Stretches the root and field to the available width.
`new(state)`	`state`	—	The caller-owned InputState entity supplies stable GPUI identity instead of a element id.
`variant(FieldVariant)`	`FieldVariant`	`FieldVariant::Primary`	Primary field chrome or the lower-emphasis surface variant.
`default_value(text)`	`text`	—	Seeds the uncontrolled InputState once.
`on_change(callback)`	`Fn(value: string) -> ()`	—	Reports each accepted query edit.
`is_required(bool)`	`bool`	`false`	Marks the field required for native form validation.
`is_invalid(bool)`	`bool`	—	Forces invalid field chrome and error state.
`validate(callback)`	`Fn(value: string) -> ValidationError \| true \| null`	—	A callback returns one optional validation message.
`validation_behavior(ValidationBehavior)`	`ValidationBehavior`	`ValidationBehavior::Native`	Selects blocking native validation or non-blocking ARIA-style validation.
`validation_errors(errors)`	`errors`	—	Server messages take precedence over custom validation.
`is_disabled(bool)`	`bool`	`false`	Removes focus, editing and clear actions and applies disabled opacity.
`is_read_only(bool)`	`bool`	`false`	Keeps focus and selection while suppressing edits and clear actions.
`name(text)`	`text`	—	Submission name stored with the current query.
`auto_focus(bool)`	`bool`	`false`	Focuses the input on its first render.
`on_submit(callback)`	`Fn(value: string) -> ()`	—	Enter reports the current query.
`on_clear(callback)`	`Fn() -> ()`	—	The clear button and Escape report an explicit clear; deleting the final character does not.
`placeholder(text)`	`text`	—	Placeholder displayed while the query is empty and unfocused.
`search_icon(element)`	`AnyElement`	`AnyElement::SearchIcon`	Replaces the leading magnifier.
`clear_icon(element)`	`AnyElement`	`AnyElement::CloseIcon`	Replaces the glyph while preserving the built-in clear action and geometry.

Parts

Search Field parts
Part	Description
`SearchField`	Root field state, label, description and error composition.
`SearchField`	Unified field shell containing icon, editable query and clear affordance.
`Input`	InputState-backed editable search query.
`SearchField`	Built-in or caller-supplied leading icon.
`Input`	Clear action with built-in or caller-supplied glyph, shown only for an editable non-empty query.

States

Search Field states
Builder	State	Description
`resolved Input validity`	`Invalid`	Hides description and applies invalid group chrome.
`is_disabled(bool)`	`Disabled`	Applies disabled opacity and removes focus, editing and clear actions.
`Input focus + apply_field_chrome`	`Focus within`	Draws focused field chrome while the input owns focus.
`SearchFieldRenderState::is_focus_visible`	`Focus visible`	Replacement content receives keyboard-visible focus state; built-in chrome uses focus-within.
`Input hover + apply_field_chrome`	`Hovered`	Uses hover fill and border while focus is outside the group.
`InputState::is_empty`	`Empty`	Removes the clear affordance from hit testing and painting.

Checkbox Checkbox Group Fieldset Label & Messages Form Input Input Group Input OTP Number Field Radio Group Text Area Text Field