@tuplo/combhook

combhook

Headless combobox hook for React

Why

We tried downshift but it was too heavy for our needs.

• No dependencies
• Tiny footprint (2.3K)
• WAI-ARIA compliant, implements the Combobox pattern
• Keyboard navigation

Install

$ npm install @tuplo/combhook

# or with yarn
$ yarn add @tuplo/combhook

Usage

Minimal example

import { useComboBox } from '@tuplo/combhook';

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>
  );
}

Options

const comboBoxProps = useComboBox({
  filterFn: async (keyword, items) =>
    items.filter((item) => item.label.includes(keyword)),
  id: 'my-combo-box',
  itemToString: (item) => item.id,
  items: [
    { id: 1, label: 'Alice' },
    { id: 2, label: 'Bob' },
  ],
  label: "Team members",
  onInputValueChange: (value) => console.log(value),
  onSelectedItemChange: (item) => console.log(item),
  placeholder: 'Choose team member',
});

filterFn

(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.

id

string | required

Unique identifier for this widget. It's used to build IDs for all child elements.

itemToString

(item: ItemType) => string | defaults to JSON.stringify(item)

If your items are stored as objects, this function is used to create unique IDs for each option.

items

ItemType[] | optional

List of initial items to show on menu. When empty, the list is populated by the return value of filterFn.

label

string | optional

Explicit value to be used on aria-label.

onInputValueChange

(value: string) => void | optional

Callback to be used when user changes the input value on the textbox.

onSelectedItemChange

(item: ItemType) => void | required

Callback to be used when user picks an item.

placeholder

string | optional

To be used as placeholder text on the textbox.

License

MIT