Select

Low-level select primitive that helps achieve accessible select menus that can be styled as needed.
Access to Fuegokit npm packages, source code repositories, and some content is limited to Appfire staff. Log in with Slack to continue.

Select is a low-level, accessible UI primitive that helps achieve ecosystem-agnostic, fully accessible select menus that can be styled as needed.

Select follows the WAI-ARIA authoring practices for a listbox that displays a menu to the user, such as a set of actions or functions triggered by a button.

Import

import { Select } from "@fuegokit/react";

Additional styling guides and examples are coming soon. For now, explore the examples at Storybook.

Usage

<Select>
<Select.Trigger aria-label="Food">
<Select.Value placeholder="Select a fruit…" />
<Select.Icon>
<AkChevronDownIcon />
</Select.Icon>
</Select.Trigger>
<Select.Portal>
<Select.Content>

Styling

To apply styles to the Select primitive, use Fuegokit React's themeGet function to access Fuegokit Tokens directly.

Component API

<StyledSelect>
<StyledSelectTrigger aria-label="Food">
<Select.Value placeholder="Select a fruit…" />
<Select.Icon UNSAFE_className="StyledSelectIcon">
<AkChevronDownIcon />
</Select.Icon>
</StyledSelectTrigger>
<Select.Portal>
<StyledSelectContent>

CSS

/apps/react-docs/examples/components/StyledSelectExample.js

const slideUpAndFade = keyframes`
from {
opacity: 0;
transform: translateY(2px);
}
to {
opacity: 1;
transform: translateY(0);
}

Accessibility

Select adheres to the listBox WAI-ARIA design pattern.

See the W3C Select-Only Combobox example for more information.

When to use

  • Inside forms when users are selecting from a list of options and will be submitting data.
  • When the experience is mostly form-based.

When not to use

Selects vs Dropdowns

Select and Dropdown components look similar but serve different purposes.

  • A Select displays a list of options. With a Select, users can select only one item from that list. It is best-suited for forms, when users are choosing an option from a select list and they intend to submit the data through the form.
  • A Dropdown displays a list of options. With a Dropdown, Users can select one or several options from that list. Dropdown options are used for taking an action, filtering, or sorting existing content.

Keyboard interactions

KeyDescription
SpaceWhen focus is on Select.Trigger, opens the select and focuses the selected item. When focus is on an item, selects the focused item.
When focus is on Select.Trigger, opens the select and focuses the first item.
EnterWhen focus is on Select.Trigger, opens the select and focuses the first item.
When focus is on an item, selects the focused item.
ArrowDownWhen focus is on Select.Trigger, opens the select.
When focus is on an item, moves focus to the next item.
ArrowUpWhen focus is on Select.Trigger, opens the select.
When focus is on an item, moves focus to the previous item.
EscCloses the select and moves focus to Select.Trigger.

Props

Select

Contains all the parts of a select.
NameTypeDefaultDescription
defaultValue
string
-The value of the select when initially rendered. Use when you do not need to control the state of the select.
value
boolean
-The controlled value of the select. Should be used in conjunction with `onValueChange`.
defaultOpen
boolean
-The open state of the select when it is initially rendered. Use when you do not need to control its open state.
open
boolean
-The controlled open state of the select. Must be used in conjunction with onOpenChange.
dir
'ltr' | 'rtl'
-The reading direction of the select when applicable. If omitted, inherits globally from `DirectionProvider` or assumes LTR (left-to-right) reading mode.
name
string
-The name of the select. Submitted with its owning form as part of a name/value pair.
disabled
boolean
-When `true`, prevents the user from interacting with select.
required
boolean
-When `true`, indicates that the user must select a value before the owning form can be submitted.
Events
NameTypeDefaultDescription
onValueChange
(value: string) => void
-Event handler called when the value changes.

Select.Trigger

The button that toggles the select. The Select.Content will position itself by aligning over the trigger.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
Data attributes
Data attributeValues
[data-state]
'open' | 'closed'
[data-disabled]
'open' | 'closed'
[data-placeholder]
'open' | 'closed'

Select.Value

The part that reflects the selected value. By default the selected item's text will be rendered. if you require more control, you can instead control the select and pass your own `children`. It should not be styled to ensure correct positioning. An optional placeholder prop is also available for when the select has no value.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
placeholder
React.ReactNode
-The content that will be rendered inside the `Select.Value` when no `value` or `defaultValue` is set.

Select.Icon

A small icon often displayed next to the value as a visual affordance for the fact it can be open. By default renders ▼ but you can use your own icon via asChild or use children.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Select.Portal

When used, portals the content part into the body.
NameTypeDefaultDescription
container
HTMLElement
document.bodySpecify a container element to portal the content into.

Select.Content

The component that pops out when the select is open.
NameTypeDefaultDescription
asChild
boolean
falseChange the default rendered element for the one passed as a child, merging their props and behavior.
position
'item-aligned' | 'popper'
'item-aligned'The positioning mode to use, `item-aligned` is the default and behaves similarly to a native MacOS menu by positioning content relative to the active item, while `popper` positions content in the same way as `Popover` and `Dropdown`.
side
'top' | 'right' | 'bottom' | 'left'
'bottom'The preferred side of the anchor to render against when open. Will be reversed when collisions occur and `avoidCollisions` is enabled. Only available when `position` is set to `popper`.
sideOffset
number
0The distance in pixels from the anchor. Only available when `position` is set to `popper`.
align
'start' | 'center' | 'end'
'start'The preferred alignment against the anchor. May change when collisions occur. Only available when `position` is set to `popper`.
alignOffset
number
0An offset in pixels from the 'start' or 'end' alignment options. Only available when `position` is set to `popper`.
avoidCollisions
boolean
trueWhen `true`, overrides the side andalign preferences to prevent collisions with boundary edges. Only available when `position` is set to `popper`.
collisionBoundary
Boundary
[]The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. Only available when `position` is set to `popper`.
collisionPadding
Padding
[]The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: `{ top: 20, left: 20 }`. Only available when `position` is set to `popper`.
arrowPadding
number
0The padding between the arrow and the edges of the content. If your content has `border-radius`, this will prevent it from overflowing the corners. Only available when `position` is set to `popper`.
sticky
'partial' | 'always'
'partial'The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless. Only available when `position` is set to `popper`.
hideWhenDetached
boolean
falseWhether to hide the content when the trigger becomes fully occluded. Only available when `position` is set to `popper`.
Events
NameTypeDefaultDescription
onCloseAutoFocus
(event: Event) => void
-Event handler called when focus moves to the trigger after closing. It can be prevented by calling `event.preventDefault`.
onEscapeKeyDown
(event: KeyboardEvent) => void
-Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`.
onPointerDownOutside
(event: PointerDownOutsideEvent) => void
-Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`.
onPointerDownOutside
(event: PointerDownOutsideEvent) => void
-The positioning mode to use, `item-aligned` is the default and behaves similarly to a native MacOS menu by positioning content relative to the active item. Positions content in the same way as `Popover` and `Dropdown`.
Data attributes
Data attributeValues
[data-state]
'open' | 'closed'
[data-side]
'left' | 'right' | 'bottom' | 'top'
[data-align]
'start' | 'end' | 'center'

Select.Viewport

The scrolling viewport that contains all of the items.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Select.Item

The component that contains the select items.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
value*
string
-The value given as data when submitted with a name.
disabled
boolean
-When `true`, prevents the user from interacting with the item.
textValue
string
-Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the `Select.ItemText` part. Use this when the content is complex, or you have non-textual content inside.
Data attributes
Data attributeValues
[data-state]
'checked' | 'unchecked'
[data-highlighted]
Present when highlighted
[data-disabled]
Present when disabled

Select.ItemText

The textual part of the item. It should only contain the text you want to see in the trigger when that item is selected. It should not be styled to ensure correct positioning.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Select.ItemIndicator

Renders when the item is selected. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Select.ScrollUpButton

An optional button used as an affordance to show the viewport overflow as well as functionaly enable scrolling upwards.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Select.ScrollDownButton

An optional button used as an affordance to show the viewport overflow as well as functionaly enable scrolling downwards.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Select.Group

Used to group multiple items. use in conjunction with Select.Label to ensure good accessibility via automatic labelling.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Select.Label

Used to render the label of a group. It won't be focusable using arrow keys.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Select.Separator

Used to visually separate items in the select.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Select.Arrow

An optional arrow element to render alongside the content. This can be used to help visually link the trigger with the Select.Content. Must be rendered inside Select.Content. Only available when `position` is set to `popper`.
NameTypeDefaultDescription
asChild
boolean
falseChange the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
width
number
10The width of the arrow in pixels.
width
number
5The height of the arrow in pixels.