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