Select

Select fields let users choose an option from a list

overviewguidelinesdeva11y
import {
  Select,
  Option,
  OptionGroup,
  OptionGroupLabel,
  createSelectCollection
} from '@cerberus/react'

Usage

The Select component is a controlled component that can be used to select one option from a set. It can be used in a group with other selects to allow for multiple selections.

Grouped Options

To group options, use the OptionGroup and OptionGroupLabel components.

Primitives

You can utilize the primitive components to customize the select.

ComponentDescription
SelectRootThe context provider for the Select family
SelectLabelThe label that appears above the select input
SelectControlThe wrapper to the select trigger that opens the dropdown
SelectTriggerhe trigger that opens the dropdown
SelectValueTextThe text that appears in the trigger
SelectIndicatorThe indicator that appears in the trigger
SelectClearTriggerThe trigger that clears the selected value
SelectPositionerThe wrapper that positions the dropdown
SelectContentThe content of the dropdown (i.e. the container itself)
SelectItemGroupThe group of options in the dropdown
SelectItemGroupLabelThe label for the group of options
SelectItemThe option in the dropdown
SelectItemTextThe text label of the option
SelectItemIndicatorThe indicator shown when the option is selected
SelectHiddenInputThe native select for the select group.

API

Select

The Select component is an abstraction of our primitives and accepts the following props:

NameDefaultDescription
placeholderThe placeholder to show in the select trigger.
size'md'The size of the select.
collectionThe collection of options to show in the dropdown.

The Select component also accepts all the props of the SelectRoot primitive props

Option

The Option component is an abstraction of our primitives and accepts the following props:

NameDefaultDescription
itemThe item to show in the dropdown. SelectCollectionItem

The Option component also accepts all the props of the SelectItem primitive props

OptionGroup

The OptionGroup component is an abstraction of our primitives and accepts the same props as the SelectItemGroup primitive.

OptionGroupLabel

The OptionGroupLabel component is an abstraction of our primitives and accepts the same props as the SelectItemGroupLabel primitive.

createSelectCollection

The createSelectCollection function is a utility function that creates a collection of options for the Select component.

export function createSelectCollection(
  collection: SelectCollectionItem[],
): ListCollection<SelectCollectionItem> {
  return createListCollection({
    items: collection,
  })
}

Parts

The SelectParts API is an Object containing the full family of components.

NameDescription
RootThe SelectRoot component which is the Provider for the family.
LabelThe SelectLabel component which displays the label and "required" notice.
ControlThe SelectControl component which is the visual field.
TriggerThe SelectTrigger component which is the trigger for the dropdown.
ClearTriggerThe SelectClearTrigger component which is the trigger to clear the selected value.
ValueTextThe SelectValueText component which displays the selected value.
IndicatorThe SelectIndicator component which displays the trigger indicator.
PositionerThe SelectPositioner component which is controls the positioning for the dropdown.
ContentThe SelectContent component which is the dropdown itself.
ItemGroupThe SelectItemGroup component which is the group of options in the dropdown.
ItemGroupLabelThe SelectItemGroupLabel component which is the label for the group of options.
ItemThe SelectItem component which is the option in the dropdown.
ItemTextThe SelectItemText component which is the text label of the option.
ItemIndicatorThe SelectItemIndicator component which displays based on the checked state.
HiddenInputThe SelectHiddenInput component which displays the native input.