Combobox

A filterable select component that allows users to search and select options.

import {
  Combobox,
  ComboItemGroup,
  ComboItemWithIndicator,
  ComboItemText
} from '@cerberus/react'

Usage

The Combobox component is an abstraction component that provides a fully functional combobox. It is built on top of the Select component and allows additional functionality such as filtering.

Select Relative

'use client'

import {
  For,
  Combobox,
  ComboItemWithIndicator,
  ComboItemText,
  useStatefulCollection,
} from '@cerberus/react'
import { Box, VStack } from 'styled-system/jsx'
import { useMemo, useState } from 'react'

const initialItems = [
  { label: 'Hades', value: 'hades' },
  { label: 'Persephone', value: 'persephone' },
  { label: 'Zeus', value: 'zeus', disabled: true },
  { label: 'Poseidon', value: 'poseidon' },
  { label: 'Hera', value: 'hera' },
]

function BasicPreview() {
  const { collection, handleInputChange } =
    useStatefulCollection(initialItems)

  return (
    <Box w="1/2">
      <Combobox
        collection={collection}
        label="Select Relative"
        onInputValueChange={handleInputChange}
        placeholder="Choose option"
      >
        <For
          each={collection.items}
          fallback={
            <VStack paddingBlock="6" w="full">
              <Text textAlign="center" textStyle="label-sm">
                No results found
              </Text>
            </VStack>
          }
        >
          {(item) => (
            <ComboItemWithIndicator key={item.value} item={item}>
              <ComboItemText>{item.label}</ComboItemText>
            </ComboItemWithIndicator>
          )}
        </For>
      </Combobox>
    </Box>
  )
}

With Start Icon

To add an icon to the start position of the input, use the startIcon prop to pass in your ReactNode.

Select Relative

'use client'

import {
  For,
  Combobox,
  ComboItemWithIndicator,
  ComboItemText,
  useStatefulCollection,
} from '@cerberus/react'
import { Box, VStack } from 'styled-system/jsx'
import { useMemo, useState } from 'react'
import { Search } from '@carbon/icons-react'

const initialItems = [
  { label: 'Hades', value: 'hades' },
  { label: 'Persephone', value: 'persephone' },
  { label: 'Zeus', value: 'zeus', disabled: true },
  { label: 'Poseidon', value: 'poseidon' },
  { label: 'Hera', value: 'hera' },
]

function StartIconPreview() {
  const { collection, handleInputChange } =
    useStatefulCollection(initialItems)

  return (
    <Box w="1/2">
      <Combobox
        collection={collection}
        label="Select Relative"
        onInputValueChange={handleInputChange}
        openOnClick
        placeholder="Choose option"
        startIcon={<Search />}
      >
        <For
          each={collection.items}
          fallback={
            <VStack paddingBlock="6" w="full">
              <Text textAlign="center" textStyle="label-sm">
                No results found
              </Text>
            </VStack>
          }
        >
          {(item) => (
            <ComboItemWithIndicator key={item.value} item={item}>
              <ComboItemText>{item.label}</ComboItemText>
            </ComboItemWithIndicator>
          )}
        </For>
      </Combobox>
    </Box>
  )
}

Grouped Items

To group items, use the ComboItemGroup component (not ComboboxItemGroup).

Select Relative

import {
  For,
  Combobox,
  ComboItemGroup,
  ComboItemWithIndicator,
  ComboItemText,
  useStatefulCollection,
} from '@cerberus/react'
import { Box } from 'styled-system/jsx'

function GroupedItemsPreview() {
  const { collection, handleInputChange } =
    useStatefulCollection(comboInitialItems)

  return (
    <Box w="1/2">
      <Combobox
        collection={collection}
        label="Select Relative"
        onInputValueChange={handleInputChange}
        placeholder="Choose option"
        startIcon={<Search />}
      >
        <ComboItemGroup label="The fam">
          <For
            each={collection.items}
            fallback={
              <VStack paddingBlock="6" w="full">
                <Text textAlign="center" textStyle="label-sm">
                  No results found
                </Text>
              </VStack>
            }
          >
            {(item) => (
              <ComboItemWithIndicator key={item.value} item={item}>
                <ComboItemText>{item.label}</ComboItemText>
              </ComboItemWithIndicator>
            )}
          </For>
        </ComboItemGroup>
      </Combobox>
    </Box>
  )
}

With Field

Wrap the Combobox component with the Field component to add additional functionality such as error and helper text when using it in a form.

Select Relative

This is saved to your profile

'use client'

import {
  For,
  Field,
  Combobox,
  ComboItemWithIndicator,
  ComboItemText,
  useStatefulCollection,
} from '@cerberus/react'
import { Box } from 'styled-system/jsx'

function FieldPreview() {
  const { collection, handleInputChange } =
    useStatefulCollection(comboInitialItems)

  return (
    <Box w="1/2">
      <Field
        label="Select Relative"
        helperText="This is saved to your profile"
        errorText="You must select something."
        required
      >
        <Combobox
          collection={collection}
          onInputValueChange={handleInputChange}
          placeholder="Choose option"
          form="myForm"
        >
          <For
            each={collection.items}
            fallback={
              <VStack paddingBlock="6" w="full">
                <Text textAlign="center" textStyle="label-sm">
                  No results found
                </Text>
              </VStack>
            }
          >
            {(item) => (
              <ComboItemWithIndicator key={item.value} item={item}>
                <ComboItemText>{item.label}</ComboItemText>
              </ComboItemWithIndicator>
            )}
          </For>
        </Combobox>
      </Field>
    </Box>
  )
}

Primitives

You can utilize the primitive components or the css prop to customize the Combobox.

Component	Description
ComboboxRoot	The context provider for the combobox family
ComboboxLabel	The label that appears above the combobox input
ComboboxControl	The wrapper to the combobox trigger that opens the dropdown
ComboboxInput	The input field of the combobox
ComboboxTrigger	he trigger that opens the dropdown
ComboboxClearTrigger	The trigger that clears the selected value
ComboboxPositioner	The wrapper that positions the dropdown
ComboboxContent	The content of the dropdown (i.e. the container itself)
ComboboxItemGroup	The group of options in the dropdown
ComboboxItemGroupLabel	The label for the group of options
ComboboxItem	The option in the dropdown
ComboboxItemText	The text label of the option
ComboboxItemIndicator	The indicator shown when the option is selected

Custom label

'use client'

import {
  For,
  Portal,
  ComboboxParts,
  useStatefulCollection,
} from '@cerberus/react'
import { Box } from 'styled-system/jsx'


function CustomDemo() {
  const { collection, handleInputChange } =
    useStatefulCollection(comboInitialItems)

  return (
    <Box w="1/2">
      <ComboboxParts.Root
        collection={collection}
        onInputValueChange={handleInputChange}
        css={{
          transform: 'skewX(-10deg)',
        }}
      >
        <ComboboxParts.Label
          css={{
            textTransform: 'uppercase',
          }}
        >
          Custom label
        </ComboboxParts.Label>

        <ComboboxParts.Control>
          <ComboboxParts.Input />

          <ComboboxParts.Trigger>
            <ChevronDownOutline />
          </ComboboxParts.Trigger>
        </ComboboxParts.Control>

        <Portal>
          <ComboboxParts.Positioner>
            <ComboboxParts.Content>
              <For
                each={collection.items}
                fallback={
                  <VStack paddingBlock="6" w="full">
                    <Text textAlign="center" textStyle="label-sm">
                      No results found
                    </Text>
                  </VStack>
                }
              >
                {(item) => (
                  <ComboboxParts.Item key={item.value} item={item}>
                    <ComboboxParts.ItemText css={{ fontSize: 'xl' }}>
                      {item.label}
                    </ComboboxParts.ItemText>
                    <ComboboxParts.ItemIndicator>
                      🔥
                    </ComboboxParts.ItemIndicator>
                  </ComboboxParts.Item>
                )}
              </For>
            </ComboboxParts.Content>
          </ComboboxParts.Positioner>
        </Portal>
      </ComboboxParts.Root>
    </Box>
  )
}

API

Combobox

The Combobox component is an abstraction of our primitives and accepts the following props:

Name	Default	Description
size	`md`	The size of the combobox.
startIcon		The icon to display at the start of the input.

The Combobox component also accepts all the props of the ComboboxRoot primitive props

ItemWithIndicator

The ItemWithIndicator component is an abstraction of our primitives and accepts all the props of the ComboboxItem primitive props

ComboItemGroup

The ComboItemGroup component is an abstraction of our primitives and accepts the following props:

Name	Default	Description
label		The label of the group.

The ComboItemGroup component is an abstraction of our primitives and accepts all the props of the ComboboxItemGroup primitive props

useStatefulCollection

The useStatefulCollection function is a utility hook that creates a collection of options and filters the list based on the user input.

function useStatefulCollection(
  initialItems: SelectCollectionItem[] = [],
): StatefulCollectionReturn

Returns

Name	Description
collection	The collection of options.
filterChars	The filter value split into an Array of chars.
handleInputChange	The function to pass to `onInputValueChange`.

Parts

The ComboboxParts API is an Object containing the full family of components.

Name	Description
Root	The `ComboboxRoot` component which is the Provider for the family.
Label	The `ComboboxLabel` component which displays the label.
Control	The `ComboboxControl` component which is the container for the visual field.
Input	The `ComboboxInput` component which is the visual field.
Trigger	The `ComboboxTrigger` component which is the trigger for the dropdown.
ClearTrigger	The `ComboboxClearTrigger` component which is the trigger to clear the value.
Positioner	The `ComboboxPositioner` component which is controls the positioning for the dropdown.
Content	The `ComboboxContent` component which is the dropdown itself.
ItemGroup	The `ComboboxItemGroup` component which is the group of options in the dropdown.
ItemGroupLabel	The `ComboboxItemGroupLabel` component which is the label for the group of options.
Item	The `ComboboxItem` component which is the option in the dropdown.
ItemText	The `ComboboxItemText` component which is the text label of the option.
ItemIndicator	The `ComboboxItemIndicator` component which displays based on the `checked` state.

On this page

Edit this page on Github