Select

A hand-drawn single-select dropdown with a fully custom, hand-implemented listbox.

Overview

A Select lets someone choose one option from a list, shown in a floating panel anchored to a button trigger. Unlike every other GHDS form control, it does not wrap a real native <select> — a native dropdown’s browser-drawn UI can’t be restyled to match the hand-drawn aesthetic, so the trigger is a real <button> but the panel and its keyboard model are hand-implemented, following the WAI-ARIA “select-only combobox” pattern.

Anatomy

A sketchy trigger button (selected value or placeholder, plus a chevron that flips when open): clicking or pressing Enter/Space/Arrow keys opens a floating listbox panel positioned below (or above, if there isn’t room) the trigger. Real DOM focus never leaves the trigger — the currently highlighted option is tracked via aria-activedescendant, not by moving focus into the panel.

Variants & States

Usage

Accessibility

• React / Web Components: role="combobox" + aria-expanded + aria-haspopup="listbox" + aria-controls on the trigger; role="listbox" on the panel; aria-activedescendant on the trigger points at the highlighted option’s id. Full keyboard support: Arrow Up/Down move the highlight (opening the panel first if closed), Home/End jump to the first/last enabled option, Enter/Space selects, Escape closes and keeps focus on the trigger, typeahead jumps to the first option whose label starts with what was just typed.
• React Native: accessibilityRole="combobox" + a direct aria-expanded prop (React Native Web does not derive aria-expanded from accessibilityState the way it does aria-disabled — confirmed directly against react-native-web’s source, the same gap already documented for Checkbox/Radio/Switch’s aria-checked). aria-haspopup, aria-controls, and aria-activedescendant have no equivalent on React Native at all — not even a manual workaround exists, since none of these are supported RN props in any form. The options panel uses accessibilityRole="menu"/"menuitem", the closest available roles (RN has no listbox/option role).
• See the Accessibility Guide for general conventions.

Content

The placeholder names what’s being chosen (“Choose a fruit”), not an instruction (“Please select”). Option labels name the option itself, not an action.

Props API

Code examples

// React — @ghds/react (children composition with SelectOption)
import { Select, SelectOption } from '@ghds/react/select';
import { useState } from 'react';

const [fruit, setFruit] = useState<string | undefined>(undefined);
<Select label="Fruit" placeholder="Choose a fruit" value={fruit} onValueChange={setFruit}>
  <SelectOption value="apple">Apple</SelectOption>
  <SelectOption value="banana">Banana</SelectOption>
  <SelectOption value="cherry" disabled>
    Cherry (out of stock)
  </SelectOption>
</Select>;

<!-- Web Components — @ghds/web-components -->
<!-- `options` is a data array (JSON attribute), not slotted children -->
<script type="module">
  import '@ghds/web-components/select';
</script>
<gh-select
  label="Fruit"
  placeholder="Choose a fruit"
  options='[{"value":"apple","label":"Apple"},{"value":"banana","label":"Banana"}]'
></gh-select>

// React Native — @ghds/react-native (data-array options, like Web Components)
import { Select } from '@ghds/react-native/select';

const FRUIT_OPTIONS = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
];
<Select label="Fruit" options={FRUIT_OPTIONS} value={fruit} onValueChange={setFruit} />;

Live Demo

React and Web Components render live below. React Native can’t run in a browser without additional react-native-web wiring (not set up in this site), so its usage is shown as a code sample instead.