hightouch UI

Select

Select presents user with a set of options and allows to select one of them.

#

#

Select should be disabled, when user shouldn't be allowed to interact with it.

Individual options can be disabled too.

You can also provide a custom message when an option is disabled:

#

Mark select as loading, when options are fetched on the fly and are not yet available.

#

Invalid select indicates that current value isn't what the system expects.

#

Clearable select should be used when empty selection is acceptable.

#

Options can display an additional descriptive text underneath the label.

#

Options can display an additional accessory view before the label. You can show an image using an image accessory. This is useful for showing logos when selecting sources or destinations, for example.

Additionally, using the showPlaceholderIcon prop will render a dotted circle in the placeholder state.

Icons can be accessories too.

#

You don't have to create objects with label and value keys as shown in the examples above. Select supports any objects, as long as you provide a label and value for each option via optionLabel and optionValue functions. description may be replaced with the optionDescription function.

#

There's a version of Select called GroupedSelect, that supports groups of options.

#

Use the heavy variant to emphasize the select when in views with many selects or in-line with text.

#

Use the alternative variant to deemphasize the select when there are many selects.

#

Use the tertiary variant when using the select inside another component.

#

The size prop impacts font-size and height. Default is set to md.

To set the width, use the width prop instead.

#

When rendering smaller-width selects, you may end up with options that are quite tall. To make the options easier to read, pass in a specific width for the popover using popoverWidth.

It is recommended to match widths, when possible.

Show a header section within the select when the options are displayed.

#

#

  • When options are not coming from user-generated content.
  • When you expect to have not more than 10 options.

#

  • Use sentence case for tab titles.

#

#

NameDefaultDescription
headerLabel

—

string

Show a header label at the top when displaying the options.

headerDescription

—

string

Show a header description at the top when displaying the options.

isDisabled

—

boolean

Determines if select is disabled.

isLoading

—

boolean

Indicates that options are being loaded.

isInvalid

—

boolean

Indicates that select is in invalid state.

isClearablefalseboolean

Determines if selection can be cleared.

isOptionDisabled

—

(option: Option) => boolean | string

Function to determine whether an option should be disabled. If a string is returned, it will be used as a disabled message.

emptyOptionsMessage"No options"string

Text to show inside a dropdown when there are no options.

options

—

Option[]

Available options. `Option` is a generic, so type of options will be inferred.

optionLabel

—

(option: Option) => string

Function to extract label from an option. If it's not provided, `label` field will be used as a label.

optionDescription

—

(option: Option) => string

Function to extract description from an option. If it's not provided, `description` field will be used as a label.

optionValue

—

(option: Option) => OptionValue

Function to extract value from an option. If it's not provided, `value` field will be used as a value.

optionAccessories

—

IconAccessoriesGetter<Option>

Function to show accessory views near the option label.

placeholder

—

string

Text to show inside select when no option is selected.

showPlaceholderIconfalseboolean

Determines if the placeholder icon should be shown. Only available when optionAccessory is defined.

removePortalfalseboolean

Determines if the select dropdown should be rendered in a portal.

variant"default""default" | "alternative" | "heavy" | "tertiary"

Determines the appearance of the select.

selectRef

—

RefObject<HTMLButtonElement>

Reference to the select element.

size"md""sm" | "md" | "lg"

Select size.

value

—

OptionValue | undefined

Selected option.

width"xs""4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "auto" | "100%"

Select width.

popoverWidthundefined"4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl"

The dropdown width. If not provided, the select width will be used.

onChange

—

(value: OptionValue | undefined) => void

Callback for when user selects a different option or clears the selection.

onClose

—

() => void

Callback for when user closes the select.

onOpen

—

() => void

Callback for when user opens the select.

valueLabel

—

(option: Option) => string

Function to format a selected option's label. If not provided, `label` field will be used as a label

#

NameDefaultDescription
isDisabled

—

boolean

Determines if select is disabled.

isLoading

—

boolean

Indicates that options are being loaded.

isInvalid

—

boolean

Indicates that select is in invalid state.

isClearablefalseboolean

Determines if selection can be cleared.

isOptionDisabled

—

(option: Option) => boolean | string

Function to determine whether an option should be disabled. If a string is returned, it will be used as a disabled message.

emptyOptionsMessage"No options"string

Text to show inside a dropdown when there are no options.

optionGroups

—

Array<{ label: string; options: Option[]; }>

Available options. `Option` is a generic, so type of options will be inferred.

optionLabel

—

(option: Option) => string

Function to extract label from an option. If it's not provided, `label` field will be used as a label.

optionDescription

—

(option: Option) => string

Function to extract description from an option. If it's not provided, `description` field will be used as a label.

optionValue

—

(option: Option) => OptionValue

Function to extract value from an option. If it's not provided, `value` field will be used as a value.

optionAccessories

—

IconAccessoriesGetter<Option>

Function to show accessories views near the option label.

placeholder

—

string

Text to show inside select when no option is selected.

removePortalfalseboolean

Determines if the select dropdown should be rendered in a portal.

selectRef

—

RefObject<HTMLButtonElement>

Reference to the select element.

showPlaceholderIconfalseboolean

Determines if the placeholder icon should be shown. Only available when optionAccessory is defined.

size"md""sm" | "md" | "lg"

Select size.

value

—

OptionValue | undefined

Selected option.

variant"default""default" | "alternative" | "heavy" | "tertiary"

Determines the appearance of the grouped select.

width"xs""4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "auto" | "100%"

Select width.

popoverWidthundefined"4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg"

The dropdown width. If not provided, the select width will be used.

onChange

—

(value: OptionValue | undefined) => void

Callback for when user selects a different option or clears the selection.

valueLabel

—

(option: Option) => string

Function to format a selected option's label. If not provided, `label` field will be used as a label.

On this page

  • Usage
  • Disabled
  • Loading
  • Invalid
  • Clearable
  • Description
  • Accessories
  • Custom objects
  • Groups
  • Heavy variant
  • Alternative variant
  • Tertiary variant
  • Size
  • Popover width
  • Header
  • Guidelines
  • When to use
  • Content
  • Props
  • Select
  • GroupedSelect