Skip to content

Select

Choose one of up to about 15 options.

<div class="cap-field" id="default">
  <label class="cap-field-label" for="sel-platform">Platform</label>
  <div class="cap-select-wrap" data-cap="select">
    <select class="cap-select" id="sel-platform" name="platform">
      <option value="cloudflare" selected>Cloudflare</option>
      <option value="vercel">Vercel</option>
      <option value="netlify">Netlify</option>
      <option value="pages">GitHub Pages</option>
      <option value="fly">Fly.io</option>
    </select>
  </div>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/select.css";
import { enhance } from "capsomer/behavior/select";

enhance();

Usage

<div class="cap-field">
  <label class="cap-field-label" for="owner">Owner <span class="cap-field-required" aria-hidden="true">Required</span></label>
  <div class="cap-select-wrap" data-cap="select">
    <select class="cap-select" id="owner" name="owner" required aria-describedby="owner-e">
      <option value="" selected>Choose an agent</option>
      <optgroup label="Agents">
        <option value="driver">capsid-driver</option>
        <option value="improve">improve-loop</option>
      </optgroup>
    </select>
  </div>
  <p class="cap-field-error" id="owner-e" hidden></p>
</div>
import { enhance } from "capsomer/behavior/select";
enhance(); // every [data-cap="select"] not marked data-native
<Select id="owner" name="owner" required value={owner} onChange={(e) => setOwner(e.target.value)}
  options={[{ value: "", label: "Choose an agent" }, { group: "Agents", options: [{ value: "driver", label: "capsid-driver" }] }]} />

Examples

Groups, a disabled option and a placeholder

<div class="cap-field">
  <label class="cap-field-label" for="sel-owner">Owner <span class="cap-field-required" aria-hidden="true">Required</span></label>
  <div class="cap-select-wrap" data-cap="select">
    <select class="cap-select" id="sel-owner" name="owner" required>
      <option value="" selected>Choose an agent</option>
      <optgroup label="Agents">
        <option value="driver">capsid-driver</option>
        <option value="improve">improve-loop</option>
        <option value="seat" disabled>seat-start (paused)</option>
      </optgroup>
      <optgroup label="People">
        <option value="alex">Alex</option>
      </optgroup>
    </select>
  </div>
</div>

Keyboard focus and hover

<p class="cap-muted">Tab to the select to see focus; Space, Enter or the arrow keys open its list. The second is shown hovered.</p>
<div class="cap-field">
  <label class="cap-field-label" for="sel-every">Check every</label>
  <div class="cap-select-wrap" data-cap="select">
    <select class="cap-select" id="sel-every">
      <option value="1">1 minute</option>
      <option value="5" selected>5 minutes</option>
      <option value="15">15 minutes</option>
      <option value="60">1 hour</option>
    </select>
  </div>
</div>
<div class="cap-field">
  <label class="cap-field-label" for="sel-hover">Region</label>
  <div class="cap-select-wrap" data-cap="select">
    <select class="cap-select" id="sel-hover">
      <option>Europe (London)</option>
      <option>United States (Ohio)</option>
    </select>
  </div>
</div>

Invalid, with its message

<div class="cap-field" data-invalid="true">
  <label class="cap-field-label" for="sel-invalid">Job owner <span class="cap-field-required" aria-hidden="true">Required</span></label>
  <div class="cap-select-wrap" data-cap="select">
    <select class="cap-select" id="sel-invalid" required aria-invalid="true" aria-describedby="sel-invalid-e">
      <option value="" selected>Choose an agent</option>
      <option value="driver">capsid-driver</option>
      <option value="improve">improve-loop</option>
    </select>
  </div>
  <p class="cap-field-error" id="sel-invalid-e">Choose who owns this job. It cannot run without an owner.</p>
</div>

Disabled, with its reason

<div class="cap-field">
  <label class="cap-field-label" for="sel-disabled">Branch</label>
  <p class="cap-field-help" id="sel-disabled-h">Locked while a deploy is running.</p>
  <div class="cap-select-wrap" data-cap="select">
    <select class="cap-select" id="sel-disabled" disabled aria-describedby="sel-disabled-h">
      <option>main</option>
      <option>build/shell</option>
    </select>
  </div>
</div>

The native select (no enhancement), small

<div class="cap-field">
  <label class="cap-field-label" for="sel-native">Sort by</label>
  <select class="cap-select" id="sel-native" data-size="sm">
    <option value="new">Newest</option>
    <option value="old">Oldest</option>
    <option value="az">A to Z</option>
  </select>
</div>
<div class="cap-field">
  <label class="cap-field-label" for="sel-native-bad">Sort by (invalid)</label>
  <select class="cap-select" id="sel-native-bad" aria-invalid="true">
    <option>Newest</option>
  </select>
</div>
<div class="cap-field">
  <label class="cap-field-label" for="sel-native-off">Sort by (disabled)</label>
  <select class="cap-select" id="sel-native-off" disabled>
    <option>Newest</option>
  </select>
</div>

Comfortable density

<div data-density="comfortable" id="sel-comfortable">
  <div class="cap-field">
    <label class="cap-field-label" for="sel-comf">Window</label>
    <div class="cap-select-wrap" data-cap="select">
      <select class="cap-select" id="sel-comf">
        <option value="24h">24 hours</option>
        <option value="7d">7 days</option>
      </select>
    </div>
  </div>
</div>

API reference

Select

PropTypeRequiredDoes
optionsArray<SelectOption | SelectGroupOption>YesOptions and groups: the same list the native select holds. Plain strings are fine for the label.
size"sm" | "default"
nativebooleanKeep the browser's own select (no popup), as on a phone.

And every attribute of <select>.

Functions

FunctionSignatureDoes
readOptions(select: HTMLSelectElement): (SelectItem | SelectGroup)[]The native select's options and groups as plain data (the popup is built from it).
triggerText(select: HTMLSelectElement): { text: string; placeholder: boolean; }The words the trigger shows: the chosen option's label, or the placeholder (the empty option's label) when the value is empty.
selectControlFor(select: Element | null): SelectControl | undefined
createSelect(wrap: HTMLElement, select: HTMLSelectElement): SelectControlBuilds the trigger and the popup for one native select and wires them.
enhance(root?: Element | Document | DocumentFragment): () => voidAttaches to every [data-cap="select"] under root not yet attached (and not data-native). Returns a function that detaches them all. The root is Element | Document | DocumentFragment, not ParentNode: under @cloudflare/workers-types an HTMLFormElement does not type as a ParentNode, so a site could not pass its form.

CSS variables

VariableDefault
--cap-input-edgevar(--line-strong)
--cap-select-min9rem

Parts and data attributes

ClassIs
.cap-selectthe root
.cap-select-icona part
.cap-select-popupa part
.cap-select-triggera part
.cap-select-valuea part
.cap-select-wrapa part
AttributeValues
data-placeholderpresent or absent
data-sizesm
StateRead from
:checkedthe platform
:disabledthe platform
:focus-visiblethe platform
:hoverthe platform
:openthe platform
[aria-expanded="true"]an attribute
[aria-invalid="true"]an attribute

Accessibility

KeyDoes
TabMoves focus to the select
Enter, Space, Down arrow, Up arrowOpens the list with the chosen option current
Letters (closed)Chooses the first option that starts with them, without opening
Down arrow, Up arrow (open)Moves the current option, skipping disabled ones
Home, End (open)First, last option
Letters (open)Moves to the next option starting with them
Enter or Space (open)Chooses the current option and closes; focus returns to the button
Esc (open)Closes without changing; focus returns to the button
Tab (open)Closes the list and moves on
  • A button with role="combobox" named by its label, with its value as its content, aria-expanded, aria-haspopup="listbox" and aria-controls.
  • The list is role="listbox" named by the label; groups are role="group" named by their heading; options are role="option" with aria-selected (the chosen one) and aria-disabled; the check is decoration.
  • Option text reaches 4.5:1 on the popup's surface in both themes; the edge of the button and the ring 3:1.
  • Hit areas at least var(--target) (the options too); inputs are 16 px on a touch screen.
  • Forced colors: the chosen option keeps its check in Highlight, the current option an outline.
  • Without script, the native select is operable by every keyboard and screen reader.