SearchBox

Introduction

The SearchBox component is a powerful autocomplete and search input for filtering, grouping, and selecting items from a list. It supports custom grouping, async API loading, validation states, custom rendering, and full reactivity via Pulse signals. SearchBox is ideal for command palettes, site-wide search, product lookup, and any scenario requiring a searchable dropdown with grouped results.

Import

import { SearchBox } from '@odyssee/components';

LiveCodeEditor Examples

Basic SearchBox

Code Éditable

Résultat

Grouped Results

Code Éditable

Résultat

Open on Focus

Code Éditable

Résultat

Minimum Search Length

Code Éditable

Résultat

Sizes

Code Éditable

Résultat

States: Disabled, Readonly, Required, Hint

Code Éditable

Résultat

Props Table

Prop	Type	Default	Description
options	SearchBox.Option[]	[]	Array of options to display in the dropdown.
value	string | Signal<string>	—	Selected value (can be reactive signal).
placeholder	string	"Search..."	Placeholder text for the input field.
disabled	boolean	false	Disables the SearchBox input.
readonly	boolean	false	Makes the SearchBox input read-only.
required	boolean	false	Marks the SearchBox as required.
label	string	—	Label displayed above the input.
hint	string	—	Optional hint text below the input.
error	string	—	Error message displayed below the input.
size	"xs" | "sm" | "md" | "lg" | "xl"	"md"	Size of the input field.
displayField	string	"name"	Field name to display for each option.
valueField	string	"id"	Field name to use as the value for each option.
searchFields	string[]	[displayField]	Fields to search/filter in the options.
groupBy	string	—	Field name to group results by.
showGroupTitles	boolean	true	Whether to show group titles in grouped results.
minSearchLength	number	0	Minimum number of characters required to trigger search/filter.
isOpenOnFocus	boolean	false	Opens dropdown when input is focused.
preventSelection	boolean	false	Prevents selection from updating the input value.
preserveSelectionOnEmpty	boolean	true	Keeps selection when input is cleared.
maxHeight	string	"max-h-72"	Maximum height for the dropdown list.
apiUrl	string	—	API endpoint for async option loading.
apiSearchQuery	string	"search"	Query parameter name for API search requests.
loading	boolean | Signal<boolean>	—	Shows a loading spinner in the dropdown.
onSelect	(item: SearchBox.Option) => void	—	Callback fired when an item is selected.
onSearch	(search: string) => void	—	Callback fired when the search input changes.
onFocus	(event: Event) => void	—	Callback fired when the input gains focus.
onBlur	(event: Event) => void	—	Callback fired when the input loses focus.
dropdownClassName	string	—	Additional CSS classes for the dropdown container.
name	string	—	Name attribute for form integration.
renderItem	(item: SearchBox.Option) => Pulse.JSX.Element	—	Custom renderer for dropdown items.
renderGroupTitle	(title: string) => Pulse.JSX.Element	—	Custom renderer for group titles.
className	string	—	Additional CSS classes for the root element.
id	string	auto-gen	Unique ID for the SearchBox input.
...rest	any	—	Other props are spread to the root element.

Implementation Notes

• Fully reactive: supports Pulse signals for value, loading, and option updates.
• Options can be filtered locally or loaded asynchronously via API.
• Customizable display, value, and search fields for flexible data structures.
• Grouping and custom group titles for organized results.
• Keyboard navigation: arrow keys, enter, escape supported.
• Validation states (error, required, disabled, readonly) affect styling and accessibility.
• Dropdown supports custom max height and scrollable content.
• Optionally renders a loading spinner and custom item/group renderers.

Accessibility

• Uses native <input type="text"> with role="combobox", aria-expanded, and aria-autocomplete.
• Dropdown uses role="listbox" and each option uses role="option".
• Label is linked via for and id attributes.
• Supports required, disabled, and readonly attributes.
• Error and hint messages are announced via text.
• Keyboard navigation and focus management are fully supported.

Best Practices

• Use displayField, valueField, and searchFields to adapt SearchBox to your data model.
• For async loading, provide a fast API and set minSearchLength to reduce requests.
• Always provide a clear label and placeholder for context.
• Use grouping for organized results in large datasets.
• Use validation states to guide user input and improve UX.
• Use custom renderers for advanced dropdown layouts (e.g., avatars, icons).

Related Links

• ComboBox component
• Input component
• Pulse Framework documentation