Skip to content

role combobox

Select draft v0.1.0

Lets people choose one option from a list that opens on demand.

A select shows the current choice in a closed box and opens a list of options when activated; the browser or the platform renders the list, its keyboard interaction and its announcements. It fits a choice among many known values (a country, a time zone, a sort order) where showing every option at once would take too much room. Two to about six options worth reading side by side are a Radio group; a list of actions is a Dropdown.

Guidelines

From apps/docs/content/components/select.md

Overview

A select shows the current choice in a closed box with a chevron, and opens a list of options when activated. The list belongs to the platform: the browser or the operating system draws it, moves through it with the keyboard and announces it. The component owns the closed box, its label, its help text and its error message, so a select looks like the other fields of a form.

This page applies to every platform. Where a platform differs, the difference sits under a sub-heading named after it (Web, iOS, Android, Desktop); everything else holds everywhere.

When to use

  • One choice among many known values: a country, a time zone, a currency, a sort order.
  • A short list of options that people already know, when the space for a Radio group is not worth it.

When not to use

  • Two to about six options worth reading side by side, especially with explanations. Use a Radio group.
  • A list of actions. Use a Dropdown: a select chooses a value, it does not perform an action.
  • Free text, or thousands of values. Use a Text field, or a searchable list.

Sizes

Size Use for
Small Dense forms, toolbars and table rows: 32 px high with 14 px text.
Medium Forms, the default: 40 px high with 16 px text.
Large A prominent single field, such as a search page or a sign-in form: 48 px high with 20 px text.

Height, inline padding and text size scale together; the label, the description and the error message keep one size. The exact values are tokens (Tokens tab). Keep one size per form.

Options and placeholder

Options are the repeated part of the component: each has a label, a value, and can be selected or disabled. The browser renders them, so the component gives them no style. A placeholder (Choose a country) is shown until a choice is made; it is a disabled first option that can never be chosen again and is not a valid value.

States

State How it happens What changes
Default Resting, closed. An outlined box with the chosen option and a chevron.
Hover A pointer rests over the box. Needs a pointing device: there is no hover on touch. The box takes the surface hover tint; the border does not change.
Focus visible Keyboard focus on the closed box. The shared focus ring appears outside the border. Pointer focus shows no ring.
Invalid invalid property, after validation. The border takes the error color and the error message appears under the box.
Disabled disabled property. Box, value, chevron, label and description drop to the shared disabled colors; the select leaves the keyboard order.

The opened list is not a state of the component: the platform draws it.

Content

  • The label is a noun phrase naming the choice: Country, Time zone, Sort by.
  • Option labels are short and parallel; order them logically (alphabetical for long lists, most common first for short ones).
  • The placeholder is an invitation to choose (Choose a country), never a value.
  • The error message says what to do: Choose a country.

Accessibility

The Specification tab lists the full accessibility contract, grouped into what holds on every platform and what is specific to one. Each statement there links the source it comes from. This section explains the decisions behind it.

Web

iOS

Android

  • Radio group (a few options, all visible)
  • Dropdown (a menu of actions)
  • Text field (free text)