Hopper

Select

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

View sourceView on npmReport an issue
AI Tip Want to skip the docs? Use the MCP Server

The select component collects user-provided information from a list of options. Selects are usually used in forms where a user submits data and chooses one option from a list. Use the select component inside a form where users are selecting from a list of option and submitting data.

Anatomy

Structure

<Select>
    <SelectItem> /* (Required) The items of the select */
        <Avatar /> /* (Optional) An avatar for the item */
        <Text /> /* (Optional) The text content of the item, required if using another element */
        <Text slot="description" /> /* (Optional) A description for the item */
        <Badge /> /* (Optional) A badge for the item */
        <Icon /> /* (Optional) An icon for the item */
    </SelectItem>
    <SelectSection> /* (Optional) A section of select items */
        <Header /> /* (Optional) A header for the section */
        <SelectItem /> /* (Required) An item in the SelectSection */
    </SelectSection>
</Select>

Composed Components

A Select uses the following components:

Avatar

Avatars are used to represent a user, a team or another entity in the Workleap ecosystem. They are often paired with text where room is available.

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

Disabled Item

A select with a disabled item.

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.

ContextualHelp

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

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 direction and align props.

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.

Multiple Selection

If you want to allow users to select multiple options from a list, use the MultiSelect component.

Multiple Selection with custom value display

Use the renderValue prop to customize how the selected values are displayed in the trigger of a MultiSelect.

Best Practices

The select component should:

  • Be used for selecting between four or more pre-defined options.
  • Have a default option selected whenever possible

Overflow content

Avoid having multiple lines of text in a select. If the text is too long for one line, add an ellipsis for overflow content, and accompany with a browser-based tooltip to show the full string of text.

Props

Select

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.

dir?
lang?
inert?
translate?
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.

SelectSection

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.

dir?
lang?
inert?
translate?

SelectItem

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.

dir?
lang?
inert?
translate?
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.

MultiSelect

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.

dir?
lang?
inert?
translate?
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.

MultiSelectSection

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.

dir?
lang?
inert?
translate?

MultiSelectItem

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.

dir?
lang?
inert?
translate?
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:

  • Item has been renamed to SelectItem.
  • The selected value only includes text. If an icon or avatar is needed, customize it using the renderValue function.
  • There is no allowFlip. Use shouldFlip.
  • There is no allowPreventOverflow. This is done automatically.
  • There is no allowResponsiveMenuWidth. Use isAutoMenuWidth.
  • 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.