ComboBox

Introduction

The ComboBox component is an advanced autocomplete input for selecting items from a list, supporting search, filtering, custom display/value fields, async API loading, validation states, and full reactivity via Pulse signals. It is ideal for forms, search/filter interfaces, and any scenario requiring a searchable dropdown.

Import

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

LiveCodeEditor Examples

Basic ComboBox

Code Éditable

Résultat

ComboBox with Label and Reactive Value

Code Éditable

Résultat

Custom Display & Value Fields

Code Éditable

Résultat

Features: Close Button, Min Search Length, Max Height

Code Éditable

Résultat

Sizes

Code Éditable

Résultat

States: Error, Disabled, Readonly, Required, Hint

Code Éditable

Résultat

Props Table

Prop	Type	Default	Description
options	ComboBox.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 ComboBox input.
readonly	boolean	false	Makes the ComboBox input read-only.
required	boolean	false	Marks the ComboBox 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.
minSearchLength	number	0	Minimum number of characters required to trigger search/filter.
showCloseButton	boolean	false	Shows a close/clear button in the input.
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.
onChange	(item: ComboBox.Option | null) => void	—	Callback fired when the selected item changes.
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: ComboBox.Option) => Pulse.JSX.Element	—	Custom renderer for dropdown items.
className	string	—	Additional CSS classes for the root element.
id	string	auto-gen	Unique ID for the ComboBox input.
...rest	any	—	Other props are spread to the root element.

Implementation Notes

• Fully reactive: supports Pulse signals for value and option updates.
• Options can be filtered locally or loaded asynchronously via API.
• Customizable display and value fields for flexible data structures.
• 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 close/clear button for quick reset.
• Custom item rendering via renderItem prop.

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 ComboBox 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 validation states to guide user input and improve UX.
• Use renderItem for custom dropdown item layouts (e.g., avatars, icons).
• Avoid excessive dropdown height; set maxHeight for usability.

Related Links

• Pulse Framework documentation
• Input component
• Select component
• FormGroup component