UnflowUI
Components

Search

A search field with a magnifier, a clear button, an optional spinner and an optional keyboard shortcut, with a debounced search callback.

Overview

Search is a type="search" field built for filtering and querying. onValueChange fires on every keystroke; onSearch fires once typing pauses for debounceMs, right away on Enter, and with an empty string when the field is cleared. While loading is set, a spinner takes the place of the clear button.

shortcut shows keycaps while the field is empty and focuses the field when those keys are pressed.

Import

import { Search } from '@unflowio/ui/components/Search';

Props

PropTypeDefaultDescription
valuestring—Controlled value
defaultValuestring''Initial value when uncontrolled
onValueChange(value: string) => void—Fired on every keystroke and when the field is cleared
onSearch(value: string) => void—Fired with the query once typing pauses for debounceMs, on Enter, and when cleared
debounceMsnumber250Delay before onSearch runs while typing. 0 runs it on every keystroke
placeholderstring'Search' (translated)Placeholder text
labelstringthe placeholderAccessible name
loadingboolean—Shows a spinner in place of the clear button
shortcutstring[]—Keys that focus the field, shown as keycaps while it is empty (e.g. ['Mod', 'k'])
listenShortcutbooleantrueSet to false to show the shortcut keycaps without listening for them
variant'outlined' | 'plain''outlined'plain drops the border and background, for toolbars and headers
size'sm' | 'md''md'Field height and text size
fullWidthbooleanfalseStretches to fill the container
disabledboolean—Disables the field

Other native input props (name, autoFocus, onKeyDown, ref, …) are passed to the <input>.

Basic usage

Last search: —

const [value, setValue] = useState('');

<Search
  placeholder="Search projects"
  value={value}
  onValueChange={setValue}
  onSearch={(query) => fetchResults(query)}
/>

Use onValueChange for state that must follow every keystroke (the field itself, client-side filtering) and onSearch for work that should wait until typing pauses, such as a request.

Shortcut

shortcut takes the same key names as Shortcut; Mod is ⌘ on Apple platforms and Ctrl elsewhere. The keycaps show while the field is empty, and pressing the keys focuses it. Set listenShortcut={false} when something else already handles the keys and the keycaps are only a hint. The preview below does that because this site uses ⌘K for its own search.

<Search placeholder="Search" shortcut={['Mod', 'k']} />

Variants, sizes and states

<Search size="sm" placeholder="Small" />
<Search placeholder="Plain" variant="plain" />
<Search placeholder="Search people" defaultValue="ana" loading />
<Search placeholder="Full width" fullWidth />
<Search placeholder="Disabled" disabled />

Customization (slots & slotProps)

SlotTypeDescription
iconReactNodeReplaces the magnifier
clearIconReactNodeReplaces the clear button's icon
startElReactNodeRendered between the icon and the field, e.g. a mode tag
Slot PropPropsDescription
inputBaseHTMLProps<HTMLInputElement>The <input> element
clearButtonOmit<IIconButton, 'icon' | 'onClick'>The clear icon button

Accessibility

  • Renders a native <input type="search">, exposed as a searchbox named by label, or by the placeholder when there is no label.
  • Clearing keeps focus in the field and calls onSearch('').
  • The clear button and spinner have translated names ("Clear search", "Searching").