Combobox

An advanced select element that can be used to allow the users select an option.

The Combobox component is an advanced version of the select element. It allows the user to search for an option and select it. Furthermore, the developer can adjust the provided options by adding groups, descriptions and images.

import { Combobox } from '@rewind-ui/core';

function App() {
  return (
    <Combobox placeholder="Select a country..." initialValue="1">
      <Combobox.Option value="1" label="Germany" />
      <Combobox.Option value="2" label="Great Britain" />
      <Combobox.Option value="3" label="Greece" />
      <Combobox.Option value="4" label="Sweden" />
      <Combobox.Option value="5" label="Japan" />
      <Combobox.Option value="6" label="China" />
      <Combobox.Option value="7" label="India" />
      <Combobox.Option value="8" label="United States" />
      <Combobox.Option value="9" label="Canada" />
      <Combobox.Option value="10" label="Mexico" />
      <Combobox.Option value="11" label="Saint Vincent and the Grenadines" />
    </Combobox>
  );
}

Import


Import the Combobox component using the following import statement.

import { Combobox } from '@rewind-ui/core';

Tones


The Combobox component supports three tones: light, solid and transparent.

<View>
  <Combobox tone="light">
    // ...
  </Combobox>
  <Combobox tone="solid">
    // ...
  </Combobox>
  <Combobox tone="transparent">
    // ...
  </Combobox>
</View>

Colors


The Combobox component supports the following colors: blue, purple, gray, dark and black.

The color property can be used to specify the color of the border and the ring on the focus state.

<View>
  <Combobox color="blue">
    // ...
  </Combobox>
  <Combobox color="purple">
    // ...
  </Combobox>
  <Combobox color="gray">
    // ...
  </Combobox>
  <Combobox color="dark">
    // ...
  </Combobox>
  <Combobox color="black">
    // ...
  </Combobox>
</View>

Option colors


Using the optionColor prop, the color of the selected option can be adjusted.

The available optionColor values are: blue, red, green, yellow, purple, gray, dark and black.

<View>
  <Combobox optionColor="blue">
    // ...
  </Combobox>
  <Combobox optionColor="red">
    // ...
  </Combobox>
  <Combobox optionColor="green">
    // ...
  </Combobox>
  <Combobox optionColor="yellow">
    // ...
  </Combobox>
  <Combobox optionColor="purple">
    // ...
  </Combobox>
  <Combobox optionColor="gray">
    // ...
  </Combobox>
  <Combobox optionColor="dark">
    // ...
  </Combobox>
  <Combobox optionColor="black">
    // ...
  </Combobox>
</View>

Modes


The following modes are supported by the Combobox component: tight and spacey.

<View>
  <Combobox mode="tight">
    // ...
  </Combobox>

  <Combobox mode="spacey">
    // ...
  </Combobox>
</View>

Sizes


The following sizes are supported by the Combobox component: xs, sm, md and lg.

<View>
  <Combobox size="xs">
    // ...
  </Combobox>

  <Combobox size="sm">
    // ...
  </Combobox>

  <Combobox size="md">
    // ...
  </Combobox>

  <Combobox size="lg">
    // ...
  </Combobox>
</View>

Radiuses


The following radiuses are supported by the Combobox component: none, sm, base, md and lg.

<View>
  <Combobox radius="none">
    // ...
  </Combobox>

  <Combobox radius="sm">
    // ...
  </Combobox>

  <Combobox radius="base">
    // ...
  </Combobox>

  <Combobox radius="md">
    // ...
  </Combobox>

  <Combobox radius="lg">
    // ...
  </Combobox>
</View>

Shadows


The following shadows are supported by the Combobox component: none, sm, base, md and lg.

<View>
  <Combobox shadow="none">
    // ...
  </Combobox>

  <Combobox shadow="sm">
    // ...
  </Combobox>

  <Combobox shadow="base">
    // ...
  </Combobox>

  <Combobox shadow="md">
    // ...
  </Combobox>

  <Combobox shadow="lg">
    // ...
  </Combobox>
</View>

Validation


The Combobox component supports the following validation options: none, invalid, valid and warning.

<View>
  <Combobox validation="none">
    // ...
  </Combobox>
  <Combobox validation="invalid">
    // ...
  </Combobox>
  <Combobox validation="valid">
    // ...
  </Combobox>
  <Combobox validation="warning">
    // ...
  </Combobox>
</View>

States


Combobox component supports disabled and loading states.

<View>
  <Combobox disabled>
    // ...
  </Combobox>
  <Combobox loading>
    // ...
  </Combobox>
</View>

Ring


A ring can be added to the Combobox by setting the withRing prop to true.

<View>
  <Combobox withRing={true}>
    // ...
  </Combobox>
  <Combobox withRing={false}>
    // ...
  </Combobox>
</View>

Icons


An icon can be added to the Combobox by setting the leftIcon prop to a valid React element.

<View>
  <Combobox leftIcon="...">
    // ...
  </Combobox>
</View>

Multiple


The Combobox component can handle multiple selections by setting the multiple prop to true. Selected options will be shown as tags.

<View>
  <Combobox multiple={true} closeOnSelect={false}>
    // ...
  </Combobox>
</View>

Clearable


The Combobox component can be made clearable by setting the clearable prop to true. Setting the clearable prop to false will hide the clear button.

<View>
  <Combobox clearable={true}>
    // ...
  </Combobox>
  <Combobox clearable={false}>
    // ...
  </Combobox>
</View>

Close on escape


The Combobox component can be made to close on escape by setting the closeOnEscape prop to true. Setting the closeOnEscape prop to false will disable this behavior.

<View>
  <Combobox closeOnEscape={true}>
    // ...
  </Combobox>
  <Combobox closeOnEscape={false}>
    // ...
  </Combobox>
</View>

Close on select


The Combobox component can be made to close on select by setting the closeOnSelect prop to true. Setting the closeOnSelect prop to false will disable this behavior.

<View>
  <Combobox closeOnSelect={true}>
    // ...
  </Combobox>
  <Combobox closeOnSelect={false}>
    // ...
  </Combobox>
</View>

Max height


The Combobox component drop down can be made to have a maximum height by setting the maxHeight prop.

<View>
  <Combobox maxHeight={200}>
    // ...
  </Combobox>
  <Combobox maxHeight={350}>
    // ...
  </Combobox>
  <Combobox maxHeight={500}>
    // ...
  </Combobox>
</View>

Min width


The Combobox component drop down can be made to have a minimum width by setting the minWidth prop.

<View>
  <Combobox minWidth={200}>
    // ...
  </Combobox>
  <Combobox minWidth={300}>
    // ...
  </Combobox>
  <Combobox minWidth={400}>
    // ...
  </Combobox>
</View>

Offset


The Combobox component drop down offset can be adjusted by setting the offset prop.

<View>
  <Combobox offset={0}>
    // ...
  </Combobox>
  <Combobox offset={5}>
    // ...
  </Combobox>
  <Combobox offset={10}>
    // ...
  </Combobox>
</View>

Searchable


The Combobox component can be made searchable by setting the searchable prop to true. Setting the searchable prop to false will disable this behavior.

<View>
  <Combobox searchable={true}>
    // ...
  </Combobox>
  <Combobox searchable={false}>
    // ...
  </Combobox>
</View>

On Search


The filtering of the Combobox component can be controlled by setting the onSearch prop. When the onSearch prop is set, the Combobox component will not filter the options automatically.

This is useful when you want to control the filtering of the options yourself. For example, when you want to filter the options based on a remote API call.

const App = () => {
  const [query, setQuery] = useState<string | null | undefined>(null);
  const filteredOptions =
    query && query.length > 0
      ? options.filter(
          (option) => option.label.toLowerCase().includes(query || '') && !option.disabled
        )
      : options;

  return (
    <>
      <Combobox placeholder="Select a country..." onSearch={(searchQuery) => setQuery(searchQuery)}>
        {filteredOptions.map((option, index) => (
          <Combobox.Option
            key={index}
            value={option.value}
            label={option.label}
            disabled={option.disabled}
          />
        ))}
      </Combobox>
    </>
  );
};

Controlled state


The Combobox component state can be controlled by setting the value and onChange props.

Single option

Value: Select a country!
const ControlledComponent = () => {
  const [value, setValue] = useState<string | string[] | null | undefined>(null);

  return (
    <>
      <Badge>Value: {value ? value : 'Select a country!'}</Badge>
      <div className="flex w-full gap-2">
        <Button onClick={() => setValue('1')}>Germany</Button>
        <Button onClick={() => setValue('2')}>Great Britain</Button>
        <Button onClick={() => setValue('3')}>Greece</Button>
      </div>

      <Template
        value={value}
        onChange={(newValue) => {
          setValue(newValue);
        }}
      />
    </>
  );
};

Multiple options

Value: Select a country!
const ControlledComponent = () => {
  const [value, setValue] = useState<string | string[] | null | undefined>(null);

  return (
    <>
      <Badge>
        Value: {Array.isArray(value) && value.length > 0 ? value.join(', ') : 'Select a country!'}
      </Badge>
      <div className="flex w-full gap-2">
        <Button onClick={() => setValue(['1', '3'])}>Germany & Greece</Button>
        <Button onClick={() => setValue(['2'])}>Great Britain</Button>
      </div>

      <Template
        value={value}
        onChange={(newValue) => {
          console.log('newValue', newValue);
          setValue(newValue);
        }}
        closeOnSelect={false}
        multiple={true}
      />
    </>
  );
};

Groups


The Combobox.Option components can be grouped using the Combobox.Group component.

The Combobox.Group component accepts a heading prop which is used as the group heading.

<View>
  <Combobox>
    <Combobox.Group heading="Europe">
      // ...
    </Combobox.Group>
    <Combobox.Group heading="Asia">
      // ...
    </Combobox.Group>
  </Combobox>
</View>

Options


Description

A description can be added to the Combobox.Option component by setting the description prop. By using the search functionality, the description will be included in the search.

<View>
  <Combobox>
    <Combobox.Option
      value="1"
      label="Germany"
      description="The second-most populous country in Europe"
    />
    // ...
  </Combobox>
</View>

Media

An image can be added to the Combobox.Option component by setting the media prop.

<View>
  <Combobox>
    <Combobox.Option
      value="1"
      label="Germany"
      media={<Image src="..." />}
    />
    // ...
  </Combobox>
</View>

API Reference


Properties

Combobox

PropTypeDescriptionDefault
clearablebooleanAdds a clear buttontrue
closeOnEscapebooleanCloses the combobox listbox on escapetrue
closeOnSelectbooleanCloses the combobox listbox on selecttrue
colorComboboxColorSets the border and ring color on focus statedark
disabledbooleanDisables comboboxfalse
initialValuestring, string[]Sets the initial value of the comboboxundefined
leftIconReactElementSets the left icon elementundefined
loadingbooleanEnables loading statefalse
maxHeightnumberSets the combobox list max height css property250
minWidthnumberSets the combobox list min width css property250
modeComboboxModeSets some or zero padding around the combobox listspacey
multiplebooleanAllows multiple selectionsfalse
optionColorComboboxOptionColorSets the selected option colorgray
offsetnumberSets the combobox list offset5
placeholderstringAdds a placeholder to the comboboxundefined
radiusComboboxRadiusSets the combobox, list and option radiusmd
searchablebooleanMakes the combobox searchabletrue
shadowComboboxShadowSets the combobox shadownone
sizeComboboxSizeSets the combobox sizemd
toneComboboxToneSets the combobox tonelight
validationComboboxValidationSets the validation statenone
valuestring, string[]Sets the controlled state valueundefined
withRingbooleanShows a ring around the combobox on active statetrue

Combobox.Group

PropTypeDescriptionDefault
headingstringSets the group headingundefined
weightComboboxGroupWeightSets the group heading font weightnormal

Combobox.Option

PropTypeDescriptionDefault
descriptionstringSets the option descriptionundefined
labelstringSets the option labelundefined
mediaReactNodeSets the option image/iconundefined
valuestringSets the option valueundefined

Events

Combobox

EventTypeDescription
onChange(value: string) => voidFires when the selected option is changed
onSearch(value: string) => voidFires when the search query string is changed

Types

Combobox

type ComboboxColor =
  | 'blue'
  | 'purple'
  | 'gray'
  | 'dark'
  | 'black';
type ComboboxOptionColor =
  | 'blue'
  | 'red'
  | 'green'
  | 'yellow'
  | 'purple'
  | 'gray'
  | 'dark'
  | 'black';
type ComboboxMode = 'spacey' | 'tight';
type ComboboxRadius = 'none' | 'sm' | 'base' | 'md' | 'lg';
type ComboboxShadow = 'none' | 'sm' | 'base' | 'md' | 'lg';
type ComboboxSize = 'xs' | 'sm' | 'md' | 'lg';
type ComboboxTone = 'light' | 'solid' | 'transparent';
type ComboboxValidation = 'none' | 'invalid' | 'valid' | 'warning';
type ComboboxGroupWeight =
  | 'thin'
  | 'extraLight'
  | 'light'
  | 'normal'
  | 'medium'
  | 'semiBold'
  | 'bold'
  | 'extraBold'
  | 'black';

Accessibility


The Combobox component adheres to the WAI-ARIA Checkbox Pattern.

Keyboard interactions

KeyDescription
Enter or SpaceSelects the focused item
Arrow UpMoves focus to the next focusable item
Arrow DownMoves focus to the previous focusable item