A simple, headless React hook for building **combobox-style autocompletes**.
npm install simple-react-comboboxA simple, headless React hook for building combobox-style autocompletes.
This library provides only behavior and state management.
You are free to render the UI however you like.
- Headless
- Lightweight
- No external dependencies
- IME-safe (Japanese / Chinese input supported)
---
``bash`
npm install simple-react-combobox
`
import { useCombobox } from "simple-react-combobox";
const items = ["Apple", "Banana", "Orange", "Grape"];
export function Example() {
const {
inputProps,
listProps,
getItemProps,
isOpen,
filteredItems,
} = useCombobox({
items,
onSelect: (item) => {
console.log("selected:", item);
},
});
return (
{isOpen && filteredItems.length > 0 && (
API
`
useCombobox(options)
`Options
`
type UseComboboxOptions = {
items: readonly T[];
itemToString?: (item: T) => string;
onSelect?: (item: T) => void;
openOnFocus?: boolean;
filterFn?: (items: readonly T[], inputValue: string) => readonly T[];
};
`items (required)The source items for the combobox.
itemToStringConverts an item to a string for display and filtering.
Default: String
onSelectCalled when an item is selected via mouse or keyboard.
openOnFocusIf true, opens the list when the input receives focus.
Default: false
filterFnCustom filtering logic.
If omitted, a case-insensitive substring match is used.
`
const defaultFilter: FilterFn = (items, input) =>
input === ""
? items
: items.filter((i) =>
itemToString(i).toLowerCase().includes(input.toLowerCase())
);
`Return Value
`
type UseComboboxResult = {
inputProps: TextInputProps;
listProps: ListProps;
getItemProps: (index: number) => ItemProps; inputValue: string;
isOpen: boolean;
setOpen: (open: boolean) => void;
highlightedIndex: number;
highlightedItem?: T;
filteredItems: readonly T[];
};
`inputPropsProps for the
.Includes:
- value
- onChange
- onKeyDown
- IME composition handlers
- ARIA attributes (
role="combobox")listPropsProps for the list container (e.g.
).Includes:
- role="listbox"
- onMouseDown guard to prevent premature blur
getItemProps(index)Props for each item element (e.g.
).Handles:
- mouse hover
- mouse selection
- ARIA attributes
inputValueThe current input value.
isOpenWhether the list is currently open.
setOpen(open: boolean)Imperatively control the open state.
Useful for closing on outside click, etc.
highlightedIndexThe currently highlighted index within filteredItems.
highlightedItemThe currently highlighted item, or undefined.
filteredItems`Items after filtering based on the current input value.
This hook does not render any UI.
You control all markup and styling.
Filtering is handled internally by default.
You can fully override it with filterFn if needed.
All indices (highlightedIndex, getItemProps) are based on
filteredItems, not the original items.
Composition events are handled internally to avoid breaking
Japanese / Chinese input.
This hook applies appropriate ARIA roles:
- combobox
- listbox
- option
You are responsible for final markup and styling.
MIT