Select

A React source recipe with Base UI behavior and the public TIS Select classes and tokens.

Functional preview

Running with the React source recipe distributed through shadcn and based on Base UI.

Loading functional preview…

Open the React · shadcn/Base UI playground

Anatomy

Country* 7

1 2 3 4

Please select a country. 5

Choose one country from the list. 6

1 Wrapper (.ds-select) — container with border, radius.
2 Icon (optional, .ds-select__icon) — leading icon, decorative.
3 Field (.ds-select__field) — native <select> element.
4 Arrow (.ds-select__arrow) — custom chevron, pointer-events: none.
5 Error message (.ds-field__error) — external, via Form Field.
6 Helper text (.ds-field__helper) — external, via Form Field.
7 Label (.ds-field__label) — external, via Form Field.

Default

Label

Helper text

Sizes

Size	Height	Font	Padding	Touch target
Small (`--sm`)	32px (`component.select.height.sm`)	`component.select.text.font-size.sm`	`component.select.padding-x.sm` / `component.field.padding-y.sm`	32px — meets WCAG 2.5.8 min (24px)
Medium (`--md`)	40px (`component.select.height.md`)	`component.select.text.font-size.md`	`component.select.padding-x.md` / `component.field.padding-y.md`	40px
Large (`--lg`)	48px (`component.select.height.lg`)	`component.select.text.font-size.lg`	`component.select.padding-x.lg` / `component.field.padding-y.lg`	48px — meets AAA 44px target

With icon

States

In Figma, State only represents exclusive visual states: Default, Hover, Focus, and Disabled. Filled, Error, and Read-only are separate properties; Error combines with Default/Hover/Focus, and Read-only combines with Default/Focus.

Error

Country*

Please select a country. Choose one country from the list.

Disabled

Readonly

Figma property	Value / CSS trigger	Visual change	Token
State	Default	Neutral border	`component.field.border-color.default`
State	Hover / `:hover`	Darker border	`component.field.border-color.hover`
State	Focus / `:focus-visible`	2px outline ring, component radius	`component.field.border-color.focus`, `component.focus-ring.*`, `component.select.focus-ring.radius.default`
State	Disabled / `[disabled]`	Muted bg + content, no pointer events	`component.field.bg.disabled`, `component.field.value.color.disabled`, `component.field.placeholder.color.disabled`
Error	True / `.ds-select--error` or `.ds-field--error .ds-select`	Red border and error focus ring	`component.field.border-color.error`, `component.focus-ring.color.error`
Error + State	True + Hover / `.ds-select--error:hover`	Darker red border	`component.field.border-color.error-hover`
Read-only	True / `.ds-select--readonly` + `[disabled]`	Readonly bg and content treatment; native select has no real readonly focus	`component.field.bg.readonly`, `component.field.value.color.readonly`

Figma properties

Property	Type	Default	Description
`Show Label`	Boolean	`true`	Shows or hides the label row (including required asterisk)
`Label`	Text	"Rótulo"	Label text (label/md)
`Required`	Boolean	`false`	Shows `*` in feedback/error/content/default next to the label
`Show Helper Text`	Boolean	`true`	Shows or hides the helper text below the control
`Helper Text`	Text	"Texto auxiliar"	Caption/sm annotation (content/secondary)

When to use

Use Select when

The user must choose exactly one option from a predefined list of 5 or more items.

Don't use Select when

Fewer than 5 options — use Radio instead. Multiple selections allowed — use Checkbox group. User needs to search or filter — use Combobox.

Best practices

Faça

Include a disabled placeholder option: <option value="" disabled selected>Choose a country</option>.

Não faça

Pre-select a real option unless it's a genuine default.

Faça

Order options logically -- alphabetical for countries, by frequency for common choices.

Não faça

Don't use a select for boolean choices -- use Toggle or Checkbox.

Content guidelines

Rule	Example
Placeholder: "Choose a..." or "Select a..." in sentence case	"Choose a country" -- not "CHOOSE A COUNTRY" or "Country"
Option text should be concise and consistent	"Brazil", "United States" -- not "The Federative Republic of Brazil"
Don't mix option types	All countries, or all languages -- not countries mixed with regions
Use sentence case for options	"Credit card" -- not "Credit Card" or "CREDIT CARD"
Always pair with a `<label>`	`<label for="country">Country</label>`

React composition

import {
  Select,
  SelectContent,
  SelectItem,
  SelectItemIndicator,
  SelectItemText,
  SelectLabel,
  SelectList,
  SelectPortal,
  SelectPositioner,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

<Select items={countries} name="country">
  <SelectLabel>País</SelectLabel>
  <SelectTrigger>
    <SelectValue placeholder="Selecione um país" />
  </SelectTrigger>
  <SelectPortal>
    <SelectPositioner>
      <SelectContent>
        <SelectList>
          {countries.map((item) => (
            <SelectItem key={item.value} value={item}>
              <SelectItemIndicator />
              <SelectItemText>{item.label}</SelectItemText>
            </SelectItem>
          ))}
        </SelectList>
      </SelectContent>
    </SelectPositioner>
  </SelectPortal>
</Select>

Status: Beta
Distribution: Source via shadcn

Installation

Configure the namespace once in the React integration guide.

npx shadcn@latest add @tis/select

pnpm dlx shadcn@latest add @tis/select

yarn dlx shadcn@latest add @tis/select

bunx --bun shadcn@latest add @tis/select

Public contract

Registry item: @tis/select
Provider: Base UI
Distribution: Source copied into the application
Status: Beta

Technical architecture

Open registry JSON

Inspect distributed source

Keyboard interaction

Key	Action
`Tab`	Moves focus to the select
`Space` / `Enter`	Opens the dropdown (browser-native)
`Arrow Up` / `Arrow Down`	Navigates options
`Escape`	Closes dropdown
Any letter	Jumps to first option starting with that letter

All keyboard interactions are handled natively by the <select> element. No custom JavaScript is required. Disabled selects are removed from tab order automatically.

Accessibility

WCAG criterion	Requirement	Status
2.4.11 Focus Appearance (AA)	Focus ring 2px + 2px gap, contrast >= 3:1 against adjacent colors	✓
2.5.8 Target Size min (AA)	Smallest size (32px) exceeds 24px minimum	✓
2.5.5 Target Size (AAA)	Large (48px) meets 44px touch target	✓
1.4.3 Contrast (AA)	Text and arrow contrast >= 4.5:1 against background. Disabled exempt.	✓
4.1.2 Name, Role, Value (A)	Use native `<select>` element. Associate with `<label>` via `for`/`id`.	✓
1.3.1 Info and Relationships (A)	Error states use `aria-invalid="true"` and `aria-describedby`.	✓
1.4.1 Use of Color (A)	Error state has visible red border + text message, not just color.	✓

Implementation notes

The custom arrow (.ds-select__arrow) uses pointer-events: none -- it is purely decorative and does not interfere with click or keyboard interaction.

Native <select> has no readonly attribute. The DS uses disabled combined with the ds-select--readonly class for visual differentiation. Unlike disabled, readonly should visually communicate that the value is set but not editable.

Required and invisible label

When Required = true, add aria-required="true" to the <select> — the visual asterisk (.ds-field__required) is decorative (aria-hidden="true"). When Show Label = false, use aria-label on the <select>. Helper Text should be linked via aria-describedby.

Output responsibility

Preserve Base UI semantics and test real content, focus visibility, and accessible names in the consuming application.

Validation evidence

Covered by its independent Storybook output plus browser, responsive, keyboard, Axe, and bundle checks.

Open the stable reference

Select

Design

Functional preview

Anatomy

Default

Sizes

With icon

States

Error

Disabled

Readonly

Figma properties

Usage

When to use

Best practices

Content guidelines

Related

React composition

Implementation

Installation

Public contract

Accessibility

Keyboard interaction

Accessibility

Output responsibility

Validation evidence