Combobox
Combobox is a composable component which allows users to filter a list of items. It includes an input field that acts as a trigger, a popover which display the list of items.
Quick Start
- Installation
npm install @adaptavant/eds-core- Import
import { Combobox } from '@adaptavant/eds-core';
Open Menu
By default, the menu opens when the user types in the trigger input. Also, using menuTrigger="focus" prop allows you to open the menu when the input is focused.
const initialOptions = [
{ id: '1', value: 'Item 1' },
{ id: '2', value: 'Item 2' },
{ id: '3', value: 'Item 3' },
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState('');
const filteredOptions = React.useMemo(() => {
if (searchTerm === '') return initialOptions;
return initialOptions.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [initialOptions, searchTerm]);
const clearAndSelect = (selectedOption) => {
setSelectedOption(selectedOption);
setSearchTerm('');
};
return (
<Field label="Select Items">
<Combobox
inputValue={searchTerm || selectedOption?.value}
menuTrigger="focus"
onClear={() => setSearchTerm('')}
onClose={() => setSearchTerm('')}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
options={filteredOptions}
selectedKey="value"
selectedOption={selectedOption}
>
<ComboboxSearchInput placeholder="Search..." />
<ComboboxPopover>
<ComboboxListbox
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
options={filteredOptions}
>
{(item) => <ComboboxItem option={item}>{item.value}</ComboboxItem>}
</ComboboxListbox>
</ComboboxPopover>
</Combobox>
</Field>
);
Size
Customise the size of the Combobox by using the size prop for the Field.
The size can be either large or standard with standard being the default.
const initialOptions = [
{ id: '1', value: 'Item 1' },
{ id: '2', value: 'Item 2' },
{ id: '3', value: 'Item 3' },
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState('');
const filteredOptions = React.useMemo(() => {
if (searchTerm === '') return initialOptions;
return initialOptions.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [initialOptions, searchTerm]);
const clearAndSelect = (selectedOption) => {
setSelectedOption(selectedOption);
setSearchTerm('');
};
return (
<Field label="Select Items" size="large">
<Combobox
inputValue={searchTerm || selectedOption?.value}
menuTrigger="focus"
onClear={() => setSearchTerm('')}
onClose={() => setSearchTerm('')}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
options={filteredOptions}
selectedKey="value"
selectedOption={selectedOption}
>
<ComboboxSearchInput placeholder="Search..." />
<ComboboxPopover>
<ComboboxListbox
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
options={filteredOptions}
>
{(item) => <ComboboxItem option={item}>{item.value}</ComboboxItem>}
</ComboboxListbox>
</ComboboxPopover>
</Combobox>
</Field>
);
Composing Trigger
Trigger as Search Input
const initialOptions = [
{ id: '1', value: 'Item 1' },
{ id: '2', value: 'Item 2' },
{ id: '3', value: 'Item 3' },
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState('');
const filteredOptions = React.useMemo(() => {
if (searchTerm === '') return initialOptions;
return initialOptions.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [initialOptions, searchTerm]);
const clearAndSelect = (selectedOption) => {
setSelectedOption(selectedOption);
setSearchTerm('');
};
return (
<Field label="Select Items">
<Combobox
inputValue={searchTerm || selectedOption?.value}
onClear={() => setSearchTerm('')}
onClose={() => setSearchTerm('')}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
options={filteredOptions}
selectedKey="value"
selectedOption={selectedOption}
>
<ComboboxSearchInput placeholder="Search..." />
<ComboboxPopover>
<ComboboxListbox
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
options={filteredOptions}
>
{(item) => <ComboboxItem option={item}>{item.value}</ComboboxItem>}
</ComboboxListbox>
</ComboboxPopover>
</Combobox>
</Field>
);
Trigger as Text Input
const initialOptions = [
{ id: '1', value: 'Item 1' },
{ id: '2', value: 'Item 2' },
{ id: '3', value: 'Item 3' },
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState('');
const filteredOptions = React.useMemo(() => {
if (searchTerm === '') return initialOptions;
return initialOptions.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [initialOptions, searchTerm]);
const clearAndSelect = (selectedOption) => {
setSelectedOption(selectedOption);
setSearchTerm('');
};
return (
<Field label="Select Items">
<Combobox
inputValue={searchTerm || selectedOption?.value}
onClear={() => setSearchTerm('')}
onClose={() => setSearchTerm('')}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
options={filteredOptions}
selectedKey="value"
selectedOption={selectedOption}
>
<ComboboxTextInput placeholder="Search..." />
<ComboboxPopover>
<ComboboxListbox
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
options={filteredOptions}
>
{(item) => <ComboboxItem option={item}>{item.value}</ComboboxItem>}
</ComboboxListbox>
</ComboboxPopover>
</Combobox>
</Field>
);
Also, if you wanted to have a custom clear.
const initialOptions = [
{ id: '1', value: 'Item 1' },
{ id: '2', value: 'Item 2' },
{ id: '3', value: 'Item 3' },
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState('');
const filteredOptions = React.useMemo(() => {
if (searchTerm === '') return initialOptions;
return initialOptions.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [initialOptions, searchTerm]);
const clearAndSelect = (selectedOption) => {
setSelectedOption(selectedOption);
setSearchTerm('');
};
return (
<Field label="Select Items">
<Combobox
inputValue={searchTerm || selectedOption?.value}
onClear={() => setSearchTerm('')}
onClose={() => setSearchTerm('')}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
options={filteredOptions}
selectedKey="value"
selectedOption={selectedOption}
>
<ComboboxTextInput
adornmentEnd={
searchTerm && (
<ClickableAdornment
className="text-primary leading-none"
onClick={() => {
setSearchTerm('');
setSelectedOption(undefined);
}}
>
<RemoveIcon size="16" />
</ClickableAdornment>
)
}
classNames={{
adornmentEnd: 'pe-2',
}}
placeholder="Search..."
/>
<ComboboxPopover>
<ComboboxListbox
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
options={filteredOptions}
>
{(item) => <ComboboxItem option={item}>{item.value}</ComboboxItem>}
</ComboboxListbox>
</ComboboxPopover>
</Combobox>
</Field>
);
Popover Customizations
The Combobox component provides several props to customise the appearance and behavior of its popover. These props allow for fine-grained control over the popover’s width, height, offset, and placement relative to the trigger element.
popoverMatchReferenceWidth: Set totrueto make the popover’s width match the trigger’s width, orfalsefor independent width.popoverMaxHeight: Sets the maximum height of the popover in pixels. The default is356.popoverMaxWidth: Sets the maximum width of the popover in pixels. The default is400.popoverOffset: Adjusts the space between the popover and the trigger, specified in pixels. The default is4.popoverPlacement: Determines the position of the popover relative to the trigger. Options include 'bottom', 'bottom-start', and 'bottom-end', allowing for flexible positioning based on the layout and space available. The default is 'bottom-start'. If there isn’t enough space for the popover to appear below the trigger, it will automatically switch to the top position.
For example:
<Combobox
popoverMatchReferenceWidth={}
popoverMaxHeight={}
popoverMaxWidth={}
popoverOffset={}
popoverPlacement={}
{...props}
>
...
</Combobox>
Strategy
Use the strategy prop to change the way how popover element will be positioned. By default, the strategy is set to absolute, changes it to fixed when the ComboboxTrigger is inside a sticky or fixed element.
This option leverages the floating-ui library, which powers the ComboboxPopover functionality.
const initialOptions = [
{ id: '1', value: 'Item 1' },
{ id: '2', value: 'Item 2' },
{ id: '3', value: 'Item 3' },
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState('');
const [showFixedElement, setShowFixedElement] = React.useState(false);
const onButtonClick = () => {
setShowFixedElement((prevState) => !prevState)
}
const filteredOptions = React.useMemo(() => {
if (searchTerm === '') return initialOptions;
return initialOptions.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [initialOptions, searchTerm]);
const clearAndSelect = (selectedOption) => {
setSelectedOption(selectedOption);
setSearchTerm('');
};
return (
<Stack className="w-full gap-4">
{showFixedElement ? (
<div className="
animate-[snackbar-transition_0.3s_cubic-bezier(0.16,_1,_0.3,_1)]
bg-neutral-secondary
fixed
flex
items-center
justify-between
mx-2
p-4
right-0
rounded-8px
shadow-40
sm:right-8
sm:w-[360px]
top-8
w-[calc(100%-16px)]
z-10
">
<Field label="Select Items">
<Combobox
inputValue={searchTerm || selectedOption?.value}
menuTrigger="focus"
onClear={() => setSearchTerm('')}
onClose={() => setSearchTerm('')}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
options={filteredOptions}
selectedKey="value"
selectedOption={selectedOption}
strategy="fixed"
>
<ComboboxSearchInput placeholder="Search..." />
<ComboboxPopover>
<ComboboxListbox
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
options={filteredOptions}
>
{(item) => <ComboboxItem option={item}>{item.value}</ComboboxItem>}
</ComboboxListbox>
</ComboboxPopover>
</Combobox>
</Field>
<button
className="
focus-visible:focus-ring
font-stronger
px-1
py-0.5
rounded-4px
text-body-12
text-primary
underline
underline-offset-2
"
onClick={onButtonClick}
>
Close
</button>
</div>
) : null}
<Button onClick={onButtonClick}>
Show fixed element
</Button>
</Stack>
);
Disabled
Utilize the isDisabled prop in the <Field/> to show that a entire Combobox isn't usable.
const initialOptions = [
{ id: '1', value: 'Item 1' },
{ id: '2', value: 'Item 2' },
{ id: '3', value: 'Item 3' },
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState('');
const filteredOptions = React.useMemo(() => {
if (searchTerm === '') return initialOptions;
return initialOptions.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [initialOptions, searchTerm]);
const clearAndSelect = (selectedOption) => {
setSelectedOption(selectedOption);
setSearchTerm('');
};
return (
<Field isDisabled label="Select Items">
<Combobox
inputValue={searchTerm || selectedOption?.value}
menuTrigger="focus"
onClear={() => setSearchTerm('')}
onClose={() => setSearchTerm('')}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
options={filteredOptions}
selectedKey="value"
selectedOption={selectedOption}
>
<ComboboxSearchInput placeholder="Search..." />
<ComboboxPopover>
<ComboboxListbox
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
options={filteredOptions}
>
{(item) => <ComboboxItem option={item}>{item.value}</ComboboxItem>}
</ComboboxListbox>
</ComboboxPopover>
</Combobox>
</Field>
);
Disabled MenuItem
Utilize the isDisabled prop in the <ComboboxItem /> component to indicate that a specific item is not selectable.
This enhances user experience by clearly displaying the disabled state. Additionally, for improved accessibility, keyboard navigation will bypass disabled MenuItems in the Listbox.
const initialOptions = [
{ id: '1', value: 'Item 1', disabled: true },
{ id: '2', value: 'Item 2', disabled: false },
{ id: '3', value: 'Item 3', disabled: true },
{ id: '4', value: 'Item 4', disabled: false },
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState('');
const filteredOptions = React.useMemo(() => {
console.log('searchTerm', searchTerm);
if (searchTerm === '') return initialOptions;
return initialOptions.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [initialOptions, searchTerm]);
const clearAndSelect = (selectedOption) => {
console.log('selectedOption', selectedOption);
setSelectedOption(selectedOption);
setSearchTerm('');
};
return (
<Field label="Select Items">
<Combobox
inputValue={searchTerm || selectedOption?.value}
menuTrigger="focus"
onClear={() => setSearchTerm('')}
onClose={() => setSearchTerm('')}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
selectedKey="value"
selectedOption={selectedOption}
>
<ComboboxSearchInput placeholder="Search..." />
<ComboboxPopover>
<ComboboxListbox
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
options={filteredOptions}
>
{(item) => <ComboboxItem option={item} isDisabled={item.disabled}>{item.value}</ComboboxItem>}
</ComboboxListbox>
</ComboboxPopover>
</Combobox>
</Field>
);
Note: Disabled item can already be selected option but having any interactions on it won't be possible.
ComboBox Group
The Combobox component supports displaying options in groups, which is useful for organizing related items into categories. This example demonstrates how to use the ComboboxListBoxGroup and ComboboxListGroup components to create a groups in combobox.
const initialOptions = [
{
label: "Leaf",
options: [
{ id: "1", value: "Cabbage" },
{ id: "2", value: "Spinach" },
{ id: "3", value: "Wheat grass" },
],
},
{
label: "Beans",
options: [
{ id: "6", value: "Chickpea" },
{ id: "7", value: "Green bean" },
{ id: "8", value: "Horse gram" },
],
},
{
label: "Bulb",
options: [
{ id: "9", value: "Garlic" },
{ id: "10", value: "Onion" },
{ id: "11", value: "Nopal" },
{ id: "12", value: "Ginger" },
{ id: "13", value: "Ginseng" },
],
},
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState("");
const filteredOptions = React.useMemo(() => {
if (searchTerm === "") return initialOptions;
return initialOptions.reduce((filtered, { label, options }) => {
const matchingOptions = options.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
if (matchingOptions.length > 0) {
filtered.push({ label, options: matchingOptions });
}
return filtered;
}, []);
}, [searchTerm]);
const clearAndSelect = (selectedOption) => {
setSelectedOption(selectedOption);
setSearchTerm("");
};
return (
<Field label="Select vegetable">
<Combobox
inputValue={searchTerm || selectedOption?.value}
menuTrigger="focus"
onClear={() => setSearchTerm("")}
onClose={() => setSearchTerm("")}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
selectedKey="value"
selectedOption={selectedOption}
>
<ComboboxSearchInput placeholder="Search..." />
<ComboboxPopover>
<ComboboxListBoxGroup
options={filteredOptions}
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
>
{({ options, label }) => {
return (
<ComboboxListGroup label={label} options={options}>
{(item) => (
<ComboboxItem
option={item}
onClick={() => {
setSelectedOption(item);
}}
>
{item.value}
</ComboboxItem>
)}
</ComboboxListGroup>
);
}}
</ComboboxListBoxGroup>
</ComboboxPopover>
</Combobox>
</Field>
);
FullScreen on Mobile
On mobile, enable fullScreenForMobile to render the sheet in full-screen with a default close button.
const initialOptions = [
{ id: "1", value: "Item 1" },
{ id: "2", value: "Item 2" },
{ id: "3", value: "Item 3" },
];
const [selectedOption, setSelectedOption] = React.useState();
const [searchTerm, setSearchTerm] = React.useState("");
const filteredOptions = React.useMemo(() => {
if (searchTerm === "") return initialOptions;
return initialOptions.filter((item) =>
item.value.toLowerCase().includes(searchTerm.toLowerCase())
);
}, [initialOptions, searchTerm]);
const clearAndSelect = (selectedOption) => {
setSelectedOption(selectedOption);
setSearchTerm("");
};
return (
<Field label="Select Items">
<Combobox
inputValue={searchTerm || selectedOption?.value}
onClear={() => setSearchTerm("")}
onInputChange={setSearchTerm}
onSelectionChange={clearAndSelect}
options={filteredOptions}
selectedKey="value"
selectedOption={selectedOption}
fullScreenForMobile
>
<ComboboxSearchInput placeholder="Search..." />
<ComboboxPopover>
<ComboboxListbox
noResultsFallback={
<Text className="text-secondary text-center text-body-12 py-4">
No matching results
</Text>
}
options={filteredOptions}
>
{(item) => <ComboboxItem option={item}>{item.value}</ComboboxItem>}
</ComboboxListbox>
</ComboboxPopover>
</Combobox>
</Field>
);
API Reference
Combobox
| Prop | Default | Description |
|---|---|---|
children | _ | ((menuState: { isMenuOpen: boolean }) => React.ReactNode) | React.ReactNodeAccepts either a React node or a render function. The render function provides the menu's state (isMenuOpen). |
closeButtonPropsForMobile? | _ | { label: string, onClick: function, size: 'large' | 'standard' | 'small' }If closeButtonPropsForMobile is provided then the mobile version of the component will have a close button |
selectedKey | _ | keyOf objectKey for identifying the selected option. |
selectedOption | _ | object | undefinedCurrently selected option from the list. |
inputValue? | _ | stringValue of the combobox input. |
menuTrigger? | input | 'focus' | 'input'Interaction type to display the Combobox menu. |
mobileFriendly? | true | booleanIndicates if the opened element should be rendered as a Sheet in mobile viewports |
onClear? | _ | () => voidFunction to be invoked for clearing the Combobox input value. |
onClose? | _ | () => voidHandler that is called when the Combobox is closed. |
onInputChange | _ | (value: string) => voidFunction to be invoked when the input value changes. |
onSelectionChange | _ | (newOption: object | undefined) => voidFunction to be invoked when the selection changes. |
popoverMatchReferenceWidth? | false | booleanMatch the width of the popover with the reference element. |
popoverMaxHeight? | 356 | numberThe max height of the popover. |
popoverMaxWidth? | 400 | numberThe max width of the popover. |
popoverOffset? | 4 | numberThe offset of the combobox popover. |
popoverPlacement? | 'bottom-start' | 'bottom' | 'bottom-start' | 'bottom-end'The placement of the popover relative to the combobox Input. |
strategy? | 'absolute' | 'absolute' | 'fixed'The strategy used to position the floating element. |
titleForMobile? | _ | stringOn mobile Combobox renders a Sheet component. If titleForMobile is provided then the Sheet will have a Header with title rendered |
fullScreenForMobile | false | booleanEnables fullscreen mode for the mobile select menu, making it cover the entire viewport. |
ComboboxInput
This API applies to both ComboboxSearchInput and ComboboxTextInput.
| Prop | Default | Description |
|---|---|---|
aria-activedescendant? | _ | stringidentifies the currently active element when using ARIA widgets. |
aria-autocomplete? | _ | 'inline' | 'list' | 'both' | 'none'Indicates whether input completion suggestions are provided, and their type. |
aria-controls? | _ | stringIdentifies the element(s) that the input controls. |
aria-expanded? | _ | booleanIndicates whether the popover is currently expanded or collapsed. |
aria-haspopup? | _ | 'dialog' | 'grid' | 'listbox' | 'menu' | 'tree' | 'boolean'Indicates the availability of a popup related to the input. |
autoComplete? | _ | stringSpecifies whether autocomplete is enabled for the input. |
autoCorrect? | _ | 'on' | 'off'Specifies whether auto-correction is enabled for the input. |
autoFocus? | _ | booleanAutomatically focuses the input element when it is rendered. |
adornmentStart? | _ | React.ReactNodeSlot to render content before the input's value. |
adornmentEnd? | _ | React.ReactNodeSlot to render content after the input's value. |
focusContainerRef? | _ | React.Ref<HTMLDivElement>Reference to the wrapper FocusContainer element. |
inputMode? | _ | 'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal' | 'search'Hints to browsers about what kind of virtual keyboard to display. |
name? | _ | stringName of the input, used for form submissions. |
onBlur? | _ | functionFunction to be invoked when the input loses focus. |
onChange? | _ | functionFunction to be invoked when a new item is selected. |
onFocus? | _ | functionFunction to be invoked when the input is focused. |
onKeyDown? | _ | functionFunction to be invoked when a key is pressed while the input is focused. |
onPaste? | _ | functionFunction to be invoked when content is pasted into the input. |
pattern? | _ | stringRegular expression pattern the input's value must match for validation. |
placeholder? | _ | stringPlaceholder text displayed when the input is empty. |
role? | _ | stringARIA role for the input. |
spellCheck? | _ | booleanSpecifies whether the input value should be checked for spelling errors. |
type? | _ | 'email' | 'password' | 'search' | 'tel' | 'text' | 'url'Type of the input element. |
ComboboxPopover
| Prop | Default | Description |
|---|---|---|
shouldUsePortal? | true | booleanDetermines whether the Popover should be rendered in a React Portal. If true, the Popover will be rendered outside the DOM hierarchy of the parent component. |
children? | _ | React.ReactNodeContent of the ComboboxList with the options. |
inputAppearance? | "TextInput" | "SearchInput" | "TextInput" | "none"Controls whether to include or exclude an input inside the mobile popover / sheet. |
inputPlaceholder? | "Search..." | stringThe placeholder text for the input inside the mobile popover / sheet. |
ComboboxListbox
| Prop | Default | Description |
|---|---|---|
noResultsFallback? | _ | React.ReactNodeComponent to render when there are no options left in the filtered result. |
options | _ | Array of ObjectsOptions to be rendered in the dropdown. |
ComboboxItem
| Prop | Default | Description |
|---|---|---|
children | _ | React.ReactNodeThe content of the combobox menu item. |
id? | _ | stringAn optional ID for the menu item; auto-generated if not provided. |
option | _ | objectOption associated with the item |
onClick? | _ | () => voidFunction to be invoked when the item is clicked. |
size? | standard | 'standard' | 'large'Size of the combobox item.
|
showSelectionIndicator? | true | booleanControls whether to show the selection indicator (check icon) for selected items. |
Style API
Our design system components include style props that allow you to easily customize different parts of each component to match your design needs.
Please refer to the Style API documentation for more insights.