Skip to main content

Installation

npm install @kuzenbo/core

Usage

import { Combobox } from "@kuzenbo/core";

const frameworks = [
  { value: "react", label: "React" },
  { value: "vue", label: "Vue" },
  { value: "svelte", label: "Svelte" },
];

function Example() {
  const [value, setValue] = useState("");

  return (
    <Combobox value={value} onValueChange={setValue}>
      <Combobox.Label>Framework</Combobox.Label>
      <Combobox.Row>
        <Combobox.Input placeholder="Select framework..." />
        <Combobox.Trigger />
      </Combobox.Row>
      <Combobox.Portal>
        <Combobox.Positioner>
          <Combobox.Popup>
            <Combobox.Content>
              <Combobox.List>
                <Combobox.Empty>No results found.</Combobox.Empty>
                <Combobox.Collection items={frameworks}>
                  {(item) => (
                    <Combobox.Item value={item.value}>
                      <Combobox.ItemIndicator />
                      {item.label}
                    </Combobox.Item>
                  )}
                </Combobox.Collection>
              </Combobox.List>
            </Combobox.Content>
          </Combobox.Popup>
        </Combobox.Positioner>
      </Combobox.Portal>
    </Combobox>
  );
}

Props

Combobox

size
'xs' | 'sm' | 'md' | 'lg' | 'xl'
default:"'md'"
The size of the combobox and its children.
value
ItemValue
The controlled value.
onValueChange
(value: ItemValue) => void
Callback when the value changes.
multiple
boolean
Whether to allow multiple selections.
disabled
boolean
Whether the combobox is disabled.
required
boolean
Whether the combobox is required.

Combobox.Input

placeholder
string
Placeholder text.
className
string
Additional CSS classes to apply.

Combobox.Item

value
ItemValue
required
The value for this item.
disabled
boolean
Whether the item is disabled.
className
string
Additional CSS classes to apply.

Combobox.Collection

items
ItemValue[]
required
The items to render.
children
(item: ItemValue) => ReactNode
required
Function to render each item.

Advanced Patterns

Multiple Selection

<Combobox multiple value={values} onValueChange={setValues}>
  <Combobox.Chips>
    {values.map((value) => (
      <Combobox.Chip key={value} value={value}>
        {value}
        <Combobox.ChipRemove />
      </Combobox.Chip>
    ))}
    <Combobox.ChipsInput />
  </Combobox.Chips>
  {/* ... */}
</Combobox>

Custom Filtering

const { useFilter, useFilteredItems } = Combobox;

function FilteredCombobox() {
  const filter = useFilter({ sensitivity: "base" });
  const filteredItems = useFilteredItems(items, filter);

  return (
    <Combobox>
      {/* ... */}
      <Combobox.Collection items={filteredItems}>
        {(item) => <Combobox.Item value={item.value}>{item.label}</Combobox.Item>}
      </Combobox.Collection>
    </Combobox>
  );
}

Grouped Items

<Combobox.List>
  <Combobox.Group>
    <Combobox.GroupLabel>Frameworks</Combobox.GroupLabel>
    <Combobox.Item value="react">React</Combobox.Item>
    <Combobox.Item value="vue">Vue</Combobox.Item>
  </Combobox.Group>
  <Combobox.Separator />
  <Combobox.Group>
    <Combobox.GroupLabel>Libraries</Combobox.GroupLabel>
    <Combobox.Item value="redux">Redux</Combobox.Item>
    <Combobox.Item value="zustand">Zustand</Combobox.Item>
  </Combobox.Group>
</Combobox.List>

Build docs developers (and LLMs) love