Primitives

Select primitives

Lower-level parts for composing a single-selection select.

React Aria SourceView as Markdown Edit on GitHub

Use these primitives when SelectField does not fit your layout. They expose the root, trigger, value, indicator, popover, listbox, and option parts that SelectField composes.

Select primitives: Basic

Open in playground

CountryChoose where you are based.

import { Field } from '@luke-ui/react/primitives/field';
import {
	SelectIndicator,
	SelectItem,
	SelectListBox,
	SelectPopover,
	SelectRoot,
	SelectTrigger,
	SelectValue,
} from '@luke-ui/react/primitives/select';
import { Stack } from '@luke-ui/react/stack';

export default () => {
	return (
		<Stack gap="space.16">
			<SelectRoot name="country" placeholder="Choose a country">
				<Field description="Choose where you are based." label="Country">
					<SelectTrigger>
						<SelectValue />
						<SelectIndicator />
					</SelectTrigger>
					<SelectPopover>
						<SelectListBox>
							<SelectItem id="au">Australia</SelectItem>
							<SelectItem id="ca">Canada</SelectItem>
							<SelectItem id="nz">New Zealand</SelectItem>
						</SelectListBox>
					</SelectPopover>
				</Field>
			</SelectRoot>
		</Stack>
	);
};

Select primitives: Basic

Loading Select primitives: Basic example

Anatomy

SelectRoot is the semantic root. It connects the trigger to the label, description, and error inside it, and normally owns the selection, open state, validation, form state, and size. SelectTrigger is the button that opens the popover, and it draws the control chrome. It holds a SelectValue, which shows the selected option, and a SelectIndicator. SelectPopover holds a SelectListBox, which holds the SelectItem options.

Put the SelectValue before the SelectIndicator.

Root props

Put placeholder and the selection, open state, validation, form, and size props on SelectRoot. value and defaultValue take a key, or null for no selection, and onChange receives the same type. A select has no read-only state.

id, className, and ref on SelectRoot target the root element. triggerId targets the trigger, and ref on SelectTrigger reaches it.

Options

Use SelectItem for options. SelectListBox accepts static children or items with a render function.

Indicator

SelectIndicator shows a chevron by default and sets data-open while the popover is open. Pass children to replace the chevron.

Select primitives: Indicator

Open in playground

import { Icon } from '@luke-ui/react/icon';
import {
	SelectIndicator,
	SelectItem,
	SelectListBox,
	SelectPopover,
	SelectRoot,
	SelectTrigger,
	SelectValue,
} from '@luke-ui/react/primitives/select';
import { Stack } from '@luke-ui/react/stack';

export default () => {
	return (
		<Stack gap="space.16">
			<SelectRoot aria-label="Sort order" defaultValue="newest">
				<SelectTrigger>
					<SelectValue />
					<SelectIndicator>
						<Icon name="expand" />
					</SelectIndicator>
				</SelectTrigger>
				<SelectPopover>
					<SelectListBox>
						<SelectItem id="newest">Newest first</SelectItem>
						<SelectItem id="oldest">Oldest first</SelectItem>
					</SelectListBox>
				</SelectPopover>
			</SelectRoot>
		</Stack>
	);
};

Select primitives: Indicator

Loading Select primitives: Indicator example

Size

Set size on SelectRoot, and the trigger, indicator, and items follow. medium is the default. Use small in compact layouts.

Pending

Pass isPending to SelectTrigger while a change is saving. The trigger keeps focus but can't be pressed or opened, and can't change the value from the trigger, until pending ends.

Validation

Set isInvalid or a validation prop on SelectRoot. The trigger takes a danger border, and FieldError inside Field shows the message and the error icon. See Validation.

Labels

The label takes textual, non-interactive content only. Place a link or button outside it. To name the select without a visible label, pass aria-labelledby or aria-label to SelectRoot.

API

SelectRootProps

SelectRootProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type	Default
allowsEmptyCollection	boolean	—
Whether the select should be allowed to be open when the collection is empty.
defaultOpen	boolean	—
Sets the default open state of the menu.
disabledKeys	Iterable<Key>	—
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
isOpen	boolean	—
Sets the open state of the menu.
placeholder	string	—
Text shown in the `SelectValue` while nothing is selected.
size		`'medium'`
Sets the size of the trigger, indicator, and items.
triggerId	string \|⁠ undefined	—
Element id for the trigger button. The root generates one when omitted.

SelectTriggerProps

SelectTriggerProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type
isPending	boolean \|⁠ undefined
Whether the trigger is pending. It keeps focus but can't be pressed or opened, and can't change the value from the trigger, until pending ends.

SelectValueProps

SelectValueProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type

SelectIndicatorProps

SelectIndicatorProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type

SelectPopoverProps

SelectPopoverProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type	Default
arrowBoundaryOffset	number	`0`
The minimum distance the arrow's edge should be from the edge of the overlay element.
arrowRef	RefObject<Element \|⁠ null>	—
A ref for the popover arrow element.
boundaryElement	Element	`document.body`
Element that that serves as the positioning boundary.
containerPadding	number	`12`
The placement padding that should be applied between the element and its surrounding container.
crossOffset	number	`0`
The additional offset applied along the cross axis between the element and its anchor element.
defaultOpen	boolean	—
Whether the overlay is open by default (uncontrolled).
getTargetRect	(target: Element) => DOMRect \|⁠ null \|⁠ undefined	`target.getBoundingClientRect()`
Overrides the target element's bounding rectangle. Useful for positioning relative to a specific point such as the mouse cursor (e.g. context menus) or text selection. Parameters target The target element.
isEntering	boolean	—
Whether the popover is currently performing an entry animation.
isExiting	boolean	—
Whether the popover is currently performing an exit animation.
isKeyboardDismissDisabled	boolean	`false`
Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided.
isNonModal	boolean	—
Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.
isOpen	boolean	—
Whether the overlay is open by default (controlled).
maxHeight	number	—
The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.
offset	number \|⁠ undefined	`4`
Distance in pixels between the trigger and the popover.
placement	Placement	`'bottom'`
The placement of the element with respect to its anchor element.
scrollRef	RefObject<Element \|⁠ null>	`overlayRef`
A ref for the scrollable region within the overlay.
shouldCloseOnInteractOutside	(element: Element) => boolean	—
When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the popover ref.
shouldFlip	boolean	`true`
Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
shouldSkipAnimation	boolean	—
Whether the popover should appear and disappear without an entry or exit animation. This is used by components such as PreviewTrigger to skip animations when quickly swapping between overlays.
shouldUpdatePosition	boolean	`true`
Whether the overlay should update its position automatically.
trigger	string	—
The name of the component that triggered the popover. This is reflected on the element as the `data-trigger` attribute, and can be used to provide specific styles for the popover depending on which element triggered it.
triggerRef	RefObject<Element \|⁠ null>	—
The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.

SelectListBoxProps

SelectListBoxProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type	Default
defaultSelectedKeys	'all' \|⁠ Iterable<Key>	—
The initial selected keys in the collection (uncontrolled).
dependencies	ReadonlyArray<any>	—
Values that should invalidate the item cache when using dynamic collections.
disabledKeys	Iterable<Key>	—
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
disallowEmptySelection	boolean	—
Whether the collection allows empty selection.
dragAndDropHooks	DragAndDropHooks<NoInfer<T>>	—
The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for the ListBox.
escapeKeyBehavior	'clearSelection' \|⁠ 'none'	`'clearSelection'`
Whether pressing the escape key should clear selection in the listbox or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually.
items	Iterable<T>	—
Item objects in the collection.
layout	'stack' \|⁠ 'grid'	`'stack'`
Whether the items are arranged in a stack or grid.
orientation	Orientation	`'vertical'`
The primary orientation of the items. Usually this is the direction that the collection scrolls.
renderEmptyState	(props: ListBoxRenderProps) => ReactNode	—
Provides content to display when there are no items in the list.
selectedKeys	'all' \|⁠ Iterable<Key>	—
The currently selected keys in the collection (controlled).
selectionBehavior	SelectionBehavior	`'toggle'`
How multiple selection should behave in the collection.
selectionMode	SelectionMode	—
The type of selection that is allowed in the collection.
shouldFocusOnHover	boolean	—
Whether options should be focused when the user hovers over them.
shouldFocusWrap	boolean	—
Whether focus should wrap around when the end/start is reached.
shouldSelectOnPressUp	boolean	—
Whether selection should occur on press up instead of press down.

SelectItemProps

SelectItemProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type
download	boolean \|⁠ string
Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
href	Href
A URL to link to. See MDN.
hrefLang	string
Hints at the human language of the linked URL. SeeMDN.
ping	string
A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy	HTMLAttributeReferrerPolicy
How much of the referrer to send when following the link. See MDN.
rel	string
The relationship between the linked resource and the current page. See MDN.
target	HTMLAttributeAnchorTarget
The target window for the link. See MDN.
textValue	string
A string representation of the item's contents, used for features like typeahead.