Select

A select displays a collapsible list of options from which the user can select one.

View sourceView on npmReport an issue

Props

isFluid?

If true, the select will take all available width.

Defaults to false.
items?

Item objects in the collection.

necessityIndicator?

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

placeholder?

The placeholder text when the select is empty.

prefix?

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

renderValue?

A function to render the value of the select. It will render the selected item's text by default.

size?

The size of the select.

Defaults to sm.
triggerProps?

The props for the select's trigger.

style?

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

children?

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

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'.
isDisabled?

Whether the input is disabled.

selectedKey?

The currently selected key in the collection (controlled).

defaultSelectedKey?

The initial selected key in the collection (uncontrolled).

onSelectionChange?

Handler that is called when the selection changes.

isOpen?

Sets the open state of the menu.

defaultOpen?

Sets the default open state of the menu.

onOpenChange?

Method that is called when the open state of the menu changes.

disabledKeys?

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

isRequired?

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

isInvalid?

Whether the input value is invalid.

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.

id?

The element's unique identifier. See MDN.

className?

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

onFocus?

Handler that is called when the element receives focus.

onBlur?

Handler that is called when the element loses focus.

onFocusChange?

Handler that is called when the element's focus status changes.

onKeyDown?

Handler that is called when a key is pressed.

onKeyUp?

Handler that is called when a key is released.

autoComplete?

Describes the type of autocomplete functionality the input should provide if any. See MDN.

name?

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

aria-label?

Defines a string value that labels the current element.

aria-labelledby?

Identifies the element (or elements) that labels the current element.

aria-describedby?

Identifies the element (or elements) that describes the object.

aria-details?

Identifies the element (or elements) that provide a detailed, extended description for the object.

excludeFromTabOrder?

Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.

slot?

A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.

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

Select

SelectOption

Select Trigger Examples

Disabled

A select 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.

Error

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

Sizes

A select has multiple sizes to choose from. The select menu also changes size based on the size of the select.

Labeling

If a visible label isn't specified, an aria-label must be provided to the select 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 select can take the width of its container.

Custom Value

A select's trigger value can be customized using the renderValue function to allow other elements such as an avatar or icon inside the trigger value.

Controlled

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

Form

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

Select Dropdown Examples

Disabled Item

A select with a disabled item.

Auto Menu Width

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

Menu placement

A select's menu can have a customized menu placement using the placement prop inside popoverProps.

Section

A select can have sections and section headers.

Footer

A select can have a footer.

Avatar

A select option can contain an avatar.

Count

A select option 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 select option can contain icons.

End Icons

A select can contain icons at the end of an option.

Loading

A select can have a loading state.

Load on scroll

A select can load more items when scrolling within.

Selection indicator

A select can have a different selection indicator.

Description

A select item can have a description.

Migration Notes

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

  • Item has been renamed to SelectOption.
  • The selected value only includes text. If an icon or avatar is needed, customize it using the renderValue function.
  • There is no align prop. Use placement inside popoverProps.
  • There is no allowFlip. Use shouldFlip inside popoverProps.
  • There is no allowPreventOverflow. This is done automatically.
  • There is no allowResponsiveMenuWidth. Use isAutoMenuWidth.
  • There is no direction. Use placement inside popoverProps.
  • disabled has been renamed to isDisabled.
  • fluid has been renamed to isFluid.
  • open has been renamed to isOpen..
  • required has been renamed to isRequired.
  • A select cannot be read-only.
  • overlayProps has been removed. Use popoverProps instead.
  • Use isInvalid instead of validationState.
  • variant has been removed.
  • zIndex has been removed.
  • Custom tooltips are not supported.