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.

Source code

Theme

Tone

Color

Mode

Size

Shadow

Radius

Multiple

Clearable

Close on escape

Close on select

Disabled

With ring

Validation

Placeholder

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

Prop	Type	Description	Default
clearable	`boolean`	Adds a clear button	`true`
closeOnEscape	`boolean`	Closes the combobox listbox on escape	`true`
closeOnSelect	`boolean`	Closes the combobox listbox on select	`true`
color	`ComboboxColor`	Sets the border and ring color on focus state	`dark`
disabled	`boolean`	Disables combobox	`false`
initialValue	`string`, `string[]`	Sets the initial value of the combobox	`undefined`
leftIcon	`ReactElement`	Sets the left icon element	`undefined`
loading	`boolean`	Enables loading state	`false`
maxHeight	`number`	Sets the combobox list max height css property	`250`
minWidth	`number`	Sets the combobox list min width css property	`250`
mode	`ComboboxMode`	Sets some or zero padding around the combobox list	`spacey`
multiple	`boolean`	Allows multiple selections	`false`
optionColor	`ComboboxOptionColor`	Sets the selected option color	`gray`
offset	`number`	Sets the combobox list offset	`5`
placeholder	`string`	Adds a placeholder to the combobox	`undefined`
radius	`ComboboxRadius`	Sets the combobox, list and option radius	`md`
searchable	`boolean`	Makes the combobox searchable	`true`
shadow	`ComboboxShadow`	Sets the combobox shadow	`none`
size	`ComboboxSize`	Sets the combobox size	`md`
tone	`ComboboxTone`	Sets the combobox tone	`light`
validation	`ComboboxValidation`	Sets the validation state	`none`
value	`string`, `string[]`	Sets the controlled state value	`undefined`
withRing	`boolean`	Shows a ring around the combobox on active state	`true`

Combobox.Group

Prop	Type	Description	Default
heading	`string`	Sets the group heading	`undefined`
weight	`ComboboxGroupWeight`	Sets the group heading font weight	`normal`

Combobox.Option

Prop	Type	Description	Default
description	`string`	Sets the option description	`undefined`
label	`string`	Sets the option label	`undefined`
media	`ReactNode`	Sets the option image/icon	`undefined`
value	`string`	Sets the option value	`undefined`

Events

Combobox

Event	Type	Description
onChange	`(value: string) => void`	Fires when the selected option is changed
onSearch	`(value: string) => void`	Fires 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

Key	Description
`Enter` or `Space`	Selects the focused item
`Arrow Up`	Moves focus to the next focusable item
`Arrow Down`	Moves focus to the previous focusable item

Checkbox Form Control