Select

Timezone󰯑

Contract

Overview

Machine-readable contract from Component Spec.

component: selectexport: Selectversion: 1tokens.visual: selectattributes: data-refineui=select-trigger

Anatomy

Part	data-refineui
root	select-trigger
select_item	select-item
select_menu	select-menu

Variants

Axis	Values
appearance	filled, plain

States

Scope	Category	Values
component	pseudo	focus-visible
component	component	data-state: open, closed, pressed, selected
component	environment	forced-colors, dir
select-trigger	component	data-state: open, closed
select-item	component	data-state: pressed, selected

Accessibility

Slot	Element	Role	Required attributes
select-trigger	button	combobox	aria-expanded: required=true, type: boolean
select-menu	div	listbox	—
select-item	div	option	aria-selected: required=true, type: boolean

Keyboard

Key	Action	Native
Escape	close	—
ArrowDown	next-trigger	—
ArrowUp	previous-trigger	—
Home	first-trigger	—
End	last-trigger	—
Enter	activate	true
Space	activate	true

Focus

Section	Property	Value
visual	required	true
visual	selector	:focus-visible

Layout

Property	Value
direction	logical
rtl	true

Tokens

Variant

Select a recipe variant — preview and Recipe → Tokens update together.

Pick a fruit󰯑

Recipe → Tokens

Slot bindings for variant="default" — declared in Select/style → tokens.

Slot	Variant	Property	Trace	Semantic	Light → foundation	Dark → foundation	Recipe class
trigger	—	background	select.background	backgroundPrimary	neutralWhite	neutral900	bg-refineui-alias-background-primary
trigger	—	border	select.border.default	borderDefault	neutral300	neutral650	border-refineui-alias-border-default
trigger	—	foreground	select.text	foregroundPrimary	primaryBlack	neutralWhite	text-refineui-alias-foreground-primary
trigger	—	placeholder	select.placeholder	foregroundPlaceholder	neutral450	neutral500	text-refineui-alias-foreground-placeholder

Component token trace

All paths in token-trace-v2.json prefixed with select.

Trace	Semantic	Light foundation	Dark foundation	Light	Dark
select.background	backgroundPrimary	neutralWhite	neutral900	#FFFFFF	#1A1A1A
select.border.default	borderDefault	neutral300	neutral650	#DBDBDB	#5B5B5B
select.border.disabled	borderDisabled	neutral250	neutral700	#E0E0E0	#404040
select.border.error	borderError	red500	red500	#FF6969	#FF6969
select.border.success	borderSuccess	green500	green500	#26B12D	#26B12D
select.disabledBackground	backgroundSurfaceDisabled	neutral150	neutral850	#F0F0F0	#222222
select.placeholder	foregroundPlaceholder	neutral450	neutral500	#BBBBBB	#A4A4A4
select.text	foregroundPrimary	primaryBlack	neutralWhite	#212121	#FFFFFF

Installation

npmyarnpnpmbun

npm install @refineui/react @refineui/tokens

Usage

import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from "@refineui/react";

<Select value={country} onValueChange={setCountry}>
  <SelectTrigger>
    <SelectValue placeholder="Select a country" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="us">United States</SelectItem>
    <SelectItem value="ca">Canada</SelectItem>
    <SelectItem value="uk">United Kingdom</SelectItem>
  </SelectContent>
</Select>

<Select size="lg" fullWidth>
  <SelectTrigger>
    <SelectValue placeholder="Choose an option" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>Fruits</SelectLabel>
      <SelectItem value="apple">Apple</SelectItem>
      <SelectItem value="banana">Banana</SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectItem value="other">Other</SelectItem>
  </SelectContent>
</Select>

API Reference

Select

Prop	Default	Type	Description
value	—	string	Controlled selected value.
defaultValue	—	string	Uncontrolled initial value.
onValueChange	—	(value: string) => void	Event handler when selection changes.
open	—	boolean	Controlled open state.
onOpenChange	—	(open: boolean) => void	Event handler when open state changes.
placeholder	—	string	Placeholder text.
size	"md"	"sm" | "md" | "lg"	Control height tier.
fullWidth	false	boolean	Stretches to full parent width.
disabled	false	boolean	Disables interaction.

SelectTrigger

Button that opens the dropdown.

Prop	Default	Type	Description
appearance	"filled"	"filled" | "plain"	Field chrome vs flush trigger for composed surfaces (Footer locale, Calendar caption).

SelectValue

Displays selected value or placeholder.

SelectContent

Dropdown panel container.

Prop	Default	Type	Description
position	"item-aligned"	"item-aligned" | "popper"	Positioning strategy.

SelectItem

Prop	Default	Type	Description
value	—	string	Item value (required).
disabled	false	boolean	Disables this item.

SelectGroup

Groups related items.

SelectLabel

Label for a group.

SelectSeparator

Visual divider between items.