Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsPlaygroundGuidesBlog
Sponsor

Select

Used to pick a value from predefined options.

SourceStorybookRecipeArk

Usage

import { Select } from "@chakra-ui/react"
<Select.Root>
  <Select.HiddenSelect />
  <Select.Label />

  <Select.Control>
    <Select.Trigger>
      <Select.ValueText />
    </Select.Trigger>
    <Select.IndicatorGroup>
      <Select.Indicator />
      <Select.ClearTrigger />
    </Select.IndicatorGroup>
  </Select.Control>

  <Select.Positioner>
    <Select.Content>
      <Select.Item />

      <Select.ItemGroup>
        <Select.ItemGroupLabel />
        <Select.Item />
      </Select.ItemGroup>
    </Select.Content>
  </Select.Positioner>
</Select.Root>

Examples

Sizes

Use the size prop to change the size of the select component.

Variants

Use the variant prop to change the appearance of the select component.

Option Group

Use the Select.ItemGroup component to group select options.

Controlled

Use the value and onValueChange props to control the select component.

Async Loading

Here's an example of how to populate the select collection from a remote source.

Hook Form

Here's an example of how to use the Select component with react-hook-form.

Disabled

Use the disabled prop to disable the select component.

Invalid

Here's an example of how to compose the Select component with the Field component to display an error state.

This is an error

Multiple

Use the multiple prop to allow multiple selections.

Positioning

Use the positioning prop to control the underlying floating-ui options of the select component.

Clear Trigger

Render the Select.ClearTrigger component to show a clear button. Clicking the clear button will clear the selected value.

Overflow

When the options are too many, the options will overflow the container due to the maxHeight set.

Item Description

Here's an example of how to render a description for each item.

Within Popover

Here's an example of how to use the Select within a Popover component.

Within Dialog

Here's an example of how to use the Select within a Dialog component.

Due to the focus trap within the dialog, it's important to change the portal target from the document's body to the dialog's content.

Alternatively, you can avoid portalling the Select.Positioner

Avatar Select

Here's an example of how to compose the Select and the Avatar.

Country Select

Here's an example of how to use the Select component to select a country.

Icon Button

Here's an example of how to trigger the select component with an IconButton.

Props

Root

PropDefaultType
collection *
ListCollection<T>

The collection of items

closeOnSelect true
boolean

Whether the select should close after an item is selected

composite true
boolean

Whether the select is a composed with other composite widgets like tabs or combobox

lazyMount false
boolean

Whether to enable lazy mounting

loopFocus false
boolean

Whether to loop the keyboard navigation through the options

unmountOnExit false
boolean

Whether to unmount on exit.

colorPalette 'gray'
'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'cyan' | 'purple' | 'pink'

The color palette of the component

variant 'outline'
'outline' | 'subtle'

The variant of the component

size 'md'
'xs' | 'sm' | 'md' | 'lg'

The size of the component

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
defaultOpen
boolean

The initial open state of the select when it is first rendered. Use when you do not need to control its open state.

defaultValue
string[]

The initial value of the select when it is first rendered. Use when you do not need to control the state of the select.

deselectable
boolean

Whether the value can be cleared by clicking the selected item. **Note:** this is only applicable for single selection

disabled
boolean

Whether the select is disabled

form
string

The associate form of the underlying select.

highlightedValue
string

The key of the highlighted item

id
string

The unique identifier of the machine.

ids
Partial<{ root: string content: string control: string trigger: string clearTrigger: string label: string hiddenSelect: string positioner: string item(id: string | number): string itemGroup(id: string | number): string itemGroupLabel(id: string | number): string }>

The ids of the elements in the select. Useful for composition.

immediate
boolean

Whether to synchronize the present change immediately or defer it to the next frame

invalid
boolean

Whether the select is invalid

multiple
boolean

Whether to allow multiple selection

name
string

The `name` attribute of the underlying select.

onExitComplete
() => void

Function called when the animation ends in the closed state

onFocusOutside
(event: FocusOutsideEvent) => void

Function called when the focus is moved outside the component

onHighlightChange
(details: HighlightChangeDetails<T>) => void

The callback fired when the highlighted item changes.

onInteractOutside
(event: InteractOutsideEvent) => void

Function called when an interaction happens outside the component

onOpenChange
(details: OpenChangeDetails) => void

Function called when the popup is opened

onPointerDownOutside
(event: PointerDownOutsideEvent) => void

Function called when the pointer is pressed down outside the component

onValueChange
(details: ValueChangeDetails<T>) => void

The callback fired when the selected item changes.

open
boolean

Whether the select menu is open

positioning
PositioningOptions

The positioning options of the menu.

present
boolean

Whether the node is present (controlled by the user)

readOnly
boolean

Whether the select is read-only

required
boolean

Whether the select is required

scrollToIndexFn
(details: ScrollToIndexDetails) => void

Function to scroll to a specific index

value
string[]

The keys of the selected items

as
React.ElementType

The underlying element to render.

unstyled
boolean

Whether to remove the component's style.

Previous

Select (Native)

Next

Separator