Combobox

Combobox is an input plus a listbox that appears beneath it. It searches and filters down options, allowing the user to select.

How to use it

Default

By default, the Combobox presents a list of suggested options upon value entry.

Autocomplete

In conjunction with user-provided filtering, the isAutocomplete prop highlights an option for selection.

Disabled

A disabled Combobox prevents user interaction. It doesn’t appear in the tab order, can’t receive focus, and may not be read aloud by a screenreader.

Grouped options

Use grouped options for categorization.

Hidden label

Combobox labels can be hidden.

Hint text

Hint text gives further clarification.

Media

Media elements add even more context to a Combobox and its options.

Multiselect

Use the isMultiselectable prop to allow multiple selections.

Multiselect tags

Follow Avatar guidelines by using Option tagProps to alter the appearance of multiselect tags.

Nested

A Combobox listbox can contain nested levels for additional categorization of options.

Search

Combobox can be used to provide search suggestions.

Select only

Add isEditable={false} to make Combobox behave like a native <select>.

Size

Combobox can be default or compact in size.

Validation

Show success, warning, and error validation messages with the Message component.

How to use it well

Narrow down options

Apply icons consistently

Configuration

• Name8.76.4•View source•View on npm
• Installnpm install @zendeskgarden/react-dropdowns.next
• Depsnpm install react react-dom styled-components @zendeskgarden/react-theming
• Importimport { Combobox, Field, Hint, Label, Message, OptGroup, Option, Tag } from '@zendeskgarden/react-dropdowns.next'

API

The Combobox component follows this structure:

<Field>  <Label />  <Combobox>    <Option />    <Option />    <OptGroup>      <Option />    </OptGroup>    {/* etc. */}  </Combobox></Field>

Use Array.map to iterate over options.

const OPTIONS = [  { value: 'Sunflower' },  {    label: 'More flowers',    options: [      { value: 'Violet' },      { value: 'Daisy' },    ]  }]
<Combobox>  {OPTIONS.map(option =>    option.options ? (      <OptGroup key={option.label} label={option.label}>        {option.options.map(groupOption => (          <Option key={groupOption.value} {...groupOption} />        ))}      </OptGroup>    ) : (      <Option key={option.value} {...option} />    )  )}</Combobox>

Match Option and OptGroup prop signatures when using wrapper components.

const OptionComponent = forwardRef((props, ref) => (  <Option {...props} ref={ref} />))
const OptGroupComponent = forwardRef((props, ref) => (  <OptGroup {...props} ref={ref} />))
<Combobox>  <OptGroupComponent label="Flowers">    <OptionComponent value="Violet" />    <OptionComponent value="Sunflower" />    <OptionComponent value="Daisy" />  </OptGroupComponent></Combobox>

Combobox

Extends HTMLAttributes<HTMLDivElement>

Nest a Combobox within a Field component.

((changes: { type: string; isExpanded?: boolean; selectionValue?: OptionValue | OptionValue[] | null; inputValue?: string | undefined; activeIndex?: number | undefined; }) => void) | undefined

((value: number) => string)

((options: { selection: ISelectedOption | ISelectedOption[] | null; inputValue?: string; }) => ReactNode)

Field

Extends HTMLAttributes<HTMLDivElement>

A Field provides accessibility attributes to the child Combobox field by associating it with the corresponding Label and Hint.

Hint

Extends HTMLAttributes<HTMLDivElement>

Nest a Hint within a Field component.

Label

Extends LabelHTMLAttributes<HTMLLabelElement>

Nest a Label within a Field component.

Message

Extends HTMLAttributes<HTMLDivElement>

The Message component applies appropriate icon and styles based on the validation provided. Nest it within a Field component.

Option

Extends LiHTMLAttributes<HTMLLIElement>

Nest an Option within a Combobox or OptGroup component.

Option.Meta

Extends HTMLAttributes<HTMLDivElement>

Nest Meta within an Option component.

OptGroup

Extends LiHTMLAttributes<HTMLLIElement>

Nest an OptGroup within a Combobox component.

Tag

Extends HTMLAttributes<HTMLDivElement>

The Tag is not intended to be used directly. It is used internally by the Combobox component to render selected options. Reference the props below for overriding Option tagProps.

Tag.Avatar

Extends HTMLAttributes<HTMLElement>

Use Avatar to render children of Option tagProps with an associated image.