ComboBox

A combo box allows the user to make a selection from a list of suggested, likely or desired values.

View sourceView on npmReport an issue

Anatomy

Header

The Header component represents a header within a Hopper container.

Section

The Section component represents a section within a Hopper container.

Composed Components

A ComboBox uses the following components:

Avatar

An avatar is used to represent a user, team or another entity.

Badge

A badge is used to bring attention to an element.

Header

A placeholder for an header section.

Icon

An icon component is used to render a custom icon.

Text

A text component is a primitive component matching Hopper's typography type scale.

Usage

Disabled

A combo box in a disabled state shows that it exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a field may become available later.

Disabled Item

A combo box with a disabled item.

Error

A combo box can be displayed in an error state to indicate that the selection is invalid.

Sizes

A combo box has multiple sizes to choose from. The combo box option also changes size based on the size of the combo box.

Labeling

If a visible label isn't specified, an aria-label must be provided to the combo box for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the ID of the labeling element instead.

Icon Prefix

An icon can be displayed at the start of the select trigger.

Text Prefix

A short text can be displayed at the start of the select trigger.

Fluid

A combo box can take the width of its container.

Controlled

A combo box can have a controlled selected value. In this example, it shows how it is possible to deselect an option.

Custom Filtering

A combo box can overridde the default useFilter function from RAC. This can be overridden using the defaultFilter prop, or by using the items prop to control the filtered list. When items is provided rather than defaultItems, combo box does no filtering of its own.

Allow Empty Collection

A combo box can be rendered with an empty collection. If you want the popover to open with a custom message, you can use the renderEmptyState prop within the listBoxProps prop.

Allow Custom Value

A combo box can allow the user to enter a custom value that does not match the list.

Form

A combo box can be part of a form. To submit the value of a combo box, make sure you specify the name property.

ContextualHelp

A ContextualHelp element may be placed next to the label to provide additional information or help about a ComboBox.

Auto Menu Width

A combo box can have a menu that automatically adjusts its width based on the longest item.

Menu placement

A combo box's menu can have a customized menu placement using the direction and align props.

Section

A combo box can have sections and section headers.

Footer

A combo box can have a footer.

Avatar

A combo box item can contain an avatar.

Count

A combo box item can contain a count using a badge.

Dynamic Lists

Options and sections can be populated from a hierarchial data structure. If a section has a header, the Collection component can be used to render the child items.

Icons

A combo box item can contain icons.

End Icons

A combo box can contain icons at the end of an option.

Loading

A combo box can have a loading state.

Load on scroll

A combo box can load more items when scrolling within.

Selection indicator

A combo box can have a different selection indicator.

Description

A combo box item can have a description.

Props

ComboBox

isLoading?

Whether the item is loading.

size?

A ListBoxItem can vary in size.

Defaults to sm.
isInvalid?

Whether or not the ListBoxItem is in an invalid state.

selectionIndicator?

The selection indicator to use. Only available if the selection mode is not "none". When set to "input", the selection indicator will be an either a radio or checkbox based on the selection mode.

Defaults to check.
radioProps?

The props for the Radio.

checkboxProps?

The props for the Checkbox.

style?

The inline style for the element. A function may be provided to compute the style based on component state.

id?

The unique id of the item.

value?

The object value that this item represents. When using dynamic collections, this is set automatically.

textValue?

A string representation of the item's contents, used for features like typeahead.

isDisabled?

Whether the item is disabled.

children?

The children of the component. A function may be provided to alter the children based on component state.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

href?

A URL to link to. See MDN.

hrefLang?

Hints at the human language of the linked URL. SeeMDN.

target?

The target window for the link. See MDN.

rel?

The relationship between the linked resource and the current page. See MDN.

download?

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.

ping?

A space-separated list of URLs to ping when the link is followed. See MDN.

referrerPolicy?

How much of the referrer to send when following the link. See MDN.

routerOptions?

Options for the configured client side router.

items?

Item objects in the section.

dependencies?

Values that should invalidate the item cache when using dynamic collections.

align?

The alignment of the menu.

Defaults to start.
direction?

The direction that the menu should open.

Defaults to bottom.
footer?

The footer of the combo box.

isAutoMenuWidth?

If true, the combo box menu will not be the width of the trigger and instead be the width of its contents.

inputRef?

A ref for the HTML input element.

isFluid?

If true, the select will take all available width.

Defaults to false.
listBoxProps?

The list box props.

placeholder?

The placeholder text when the select is empty.

popoverProps?

The props for the popover.

prefix?

An icon or text to display at the start of the select trigger.

shouldFlip?

Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.

triggerProps?

The props for the select's trigger.

validationBehavior?

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

Defaults to 'native'.
selectedKey?

The currently selected key in the collection (controlled).

defaultSelectedKey?

The initial selected key in the collection (uncontrolled).

shouldFocusWrap?

Whether keyboard navigation is circular.

defaultItems?

The list of ComboBox items (uncontrolled).

inputValue?

The value of the ComboBox input (controlled).

defaultInputValue?

The default value of the ComboBox input (uncontrolled).

allowsCustomValue?

Whether the ComboBox allows a non-item matching input value to be set.

menuTrigger?

The interaction required to display the ComboBox menu.

Defaults to 'input'.
disabledKeys?

The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

isReadOnly?

Whether the input can be selected but not changed by the user.

isRequired?

Whether user input is required on the input before form submission.

validate?

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.

autoFocus?

Whether the element should receive focus on render.

name?

The name of the input element, used when submitting an HTML form. See MDN.

defaultFilter?

The filter function used to determine if a option should be included in the combo box list.

formValue?

Whether the text or key of the selected item is submitted as part of an HTML form. When allowsCustomValue is true, this option does not apply and the text is always submitted.

Defaults to 'key'.
allowsEmptyCollection?

Whether the combo box allows the menu to be open when the collection is empty.

description?

The helper message of the field.

errorMessage?

The error message of the field.

label?

The label of the field.

necessityIndicator?

Whether the required state should be shown as an asterisk or a label, which would display (Optional) on all non required field labels.

contextualHelp?

A ContextualHelp element to place next to the label.

ComboBoxSection

style?

The inline style for the element.

children?

Static child items or a function to render children.

items?

Item objects in the section.

id?

The unique id of the section.

value?

The object value that this section represents. When using dynamic collections, this is set automatically.

dependencies?

Values that should invalidate the item cache when using dynamic collections.

className?

The CSS className for the element.

ComboBoxItem

isLoading?

Whether the item is loading.

size?

A ListBoxItem can vary in size.

Defaults to sm.
isInvalid?

Whether or not the ListBoxItem is in an invalid state.

selectionIndicator?

The selection indicator to use. Only available if the selection mode is not "none". When set to "input", the selection indicator will be an either a radio or checkbox based on the selection mode.

Defaults to check.
radioProps?

The props for the Radio.

checkboxProps?

The props for the Checkbox.

style?

The inline style for the element. A function may be provided to compute the style based on component state.

id?

The unique id of the item.

value?

The object value that this item represents. When using dynamic collections, this is set automatically.

textValue?

A string representation of the item's contents, used for features like typeahead.

isDisabled?

Whether the item is disabled.

children?

The children of the component. A function may be provided to alter the children based on component state.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

href?

A URL to link to. See MDN.

hrefLang?

Hints at the human language of the linked URL. SeeMDN.

target?

The target window for the link. See MDN.

rel?

The relationship between the linked resource and the current page. See MDN.

download?

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.

ping?

A space-separated list of URLs to ping when the link is followed. See MDN.

referrerPolicy?

How much of the referrer to send when following the link. See MDN.

routerOptions?

Options for the configured client side router.

Migration Notes

Coming from Orbiter, you should be aware of the following changes:

Assuming you will use ComboBox for the Autocomplete of Orbiter.

  • allowFlip has been renamed shouldFlip.
  • allowPreventOverflow has been removed.
  • boundaryElement has been removed.
  • clearOnSelect has been removed.
  • defaultOpen has been removed.
  • defaultValue has been renamed defaultInputValue.
  • fluid has been renamed isFluid.
  • icon has been removed.
  • loading has been renamed isLoading.
  • noResultsMessage has been removed. See new usage.
  • onSearch has been removed.
  • wrapperProps has been removed. There is now popoverProps for the Popover and listboxProps for the Listbox.