We tried downshift
but it was too heavy for our needs.
- No dependencies
- Tiny footprint (1.12 kB)
- WAI-ARIA compliant, implements the Combobox pattern
- Keyboard navigation
$ npm install @tuplo/use-combo-box
# or with yarn
$ yarn add @tuplo/use-combo-box
Minimal example
import { useComboBox } from "@tuplo/use-combo-box";
function ComboBox() {
const {
getComboBoxProps,
getInputProps,
getItemProps,
getLabelProps,
getMenuProps,
getToggleButtonProps,
items,
} = useComboBox({
id: "my-combo-box",
onSelectedItemChange: (item) => console.log(item),
});
return (
<div>
<label {...getLabelProps()}>Choose</label>
<div {...getComboBoxProps()}>
<input {...getInputProps()} />
<button {...getToggleButtonProps()}>Toggle</button>
</div>
<ul {...getMenuProps()}>
{items.map((item, index) => (
<li key={item.label} {...getItemProps({ item, index })}>
{item.label}
</li>
))}
</ul>
</div>
);
}
const comboBoxProps = useComboBox({
filterFn: async (keyword, items) =>
items.filter((item) => item.label.includes(keyword)),
id: "my-combo-box",
initialIsOpen: true,
items: [
{ id: "item-1", label: "Alice" },
{ id: "item-2", label: "Bob" },
],
itemToString: (item) => item.id,
label: "Team members",
onInputValueChange: (value) => console.log(value),
onSelectedItemChange: (item) => console.log(item),
placeholder: "Choose team member",
selectedValues: ["item-1", "item-2"]
});
(keyword: string, items: ItemType[]) => Promise<ItemType[]>
| optional
A custom function to be called when filtering the list of items according to the keyword typed in by the user.
string
| required
Unique identifier for this widget. It's used to build IDs for all child elements.
boolean
| optional
Sets the open state of the menu when the combo-box is initialized.
(item: ItemType) => string
| defaults toJSON.stringify(item)
If your items are stored as objects, this function is used to create unique IDs for each option.
ItemType[]
| optional
List of initial items to show on menu. When empty, the list is populated by the return value of filterFn
.
string
| optional
Explicit value to be used on aria-label
.
(value: string) => void
| optional
Callback to be used when user changes the input value on the textbox.
(item: ItemType) => void
| required
Callback to be used when user picks an item.
string
| optional
To be used as placeholder text on the textbox.
string
| optional
The selected value. Makes it a single-selection combo-box.
string[]
| optional
List of selected values. Makes it a multi-selection combo-box.
MIT