WheelPicker

Props

Per-library notes

• Svelte bind:value; React controlled (value and onChange); Vue v-model; Angular [(value)], no rest-props spread; Web Components reads child <option> elements (or the options property) and fires change; Alpine lilyWheelPicker({ options, value, … }) fires change with { value }.
• HTML: the options are in the markup; the snippet's <script> handles the keys, clicks and the hidden input, and fires a bubbling change with detail.value. The key model inside the script is generated from the shared module between its BEGIN/END markers.
• Nunjucks: a server cannot handle keys, so the macro renders the markup contract only (selected option, aria-activedescendant, data-loop, data-page-size); add the HTML script or use the Web Components element for the behaviour.
• Blazor (no JS interop): @bind-Value, key model WheelPickerKeys. A handler cannot call preventDefault for only some keys, so the arrow and page keys also scroll the list (give .wheel-picker-list overflow: hidden to stop that), and the chosen option is not re-centred by script.

Keyboard Interactions

ARIA

• role="listbox", aria-label, aria-orientation="vertical", aria-activedescendant (the chosen option), aria-disabled when disabled
• Options: role="option", aria-selected, aria-disabled when disabled

When to Use

• Choosing one value from a short, ordered list: hours, minutes, months, years, quantities
• Time and date entry where the reader scrolls or types to the value
• When a visible, scannable list is better than opening a dropdown

When Not to Use

• Use Select or Combobox — for a long list, or one the reader should search
• Use RadioGroup — for two to five choices that should all be visible at once
• Use Slider — for a continuous or very wide numeric range
• Use DateTimePicker — for a full date and time, which composes this for its time columns
• Do not use it for several selections: it is single-select

Headless

This component decides the roles, the keys and the chosen value. It decides no height, snapping, fading, colour or motion; the consumer's CSS supplies the wheel look.

Styles

Target .wheel-picker, .wheel-picker-list (give it a height and overflow-y: auto, with scroll-snap-type: y mandatory) and .wheel-picker-option (scroll-snap-align: center). Style the chosen option with [aria-selected="true"] and a disabled one with [aria-disabled="true"]. Never remove the list's focus ring. Under prefers-reduced-motion, drop any scroll smoothing, fade or tilt.

Testing

• Base class first, then the consumer class; a vertical, named listbox
• One option per entry, exactly one aria-selected, none for an unknown value; aria-activedescendant names it
• Arrow, Home, End and Page keys move the choice, skip disabled options, clamp or wrap with loop
• Type-ahead chooses the matching option
• Handled keys prevent the default action
• Clicking chooses an enabled option; a disabled one does nothing; the held option is a no-op
• Disabled: not focusable, ignores keys and clicks
• Hidden input only with name, carrying the value; rest props reach the root

Advice

Give the list a fixed height showing three to seven options, so the chosen one has neighbours on both sides. Keep labels short and put the unit in label, not in every option. For a form field, give the picker a visible label and name.

A wheel is easy to use with a pointer and keyboard but is a poor fit for screen-magnifier users who see one option at a time: for a long list, offer a Select instead.

Implementation Notes

• Renders <div class="wheel-picker {class}"> holding <div class="wheel-picker-list" role="listbox" aria-orientation="vertical" tabindex="0"> of <div class="wheel-picker-option" role="option" aria-selected> elements
• DOM focus stays on the list; the cursor is aria-activedescendant. Selection follows the cursor, so there is no commit key (APG listbox, "selection follows focus")
• The keys, the skipping of disabled options, the wrap rule and type-ahead are the pure shared/wheel-picker.ts
• Centres the chosen option by setting the list's scrollTop: only the list scrolls, never the page, and never animated
• The wheel look (scroll snapping, a fading edge, a 3-D tilt, momentum on touch) is the consumer's CSS. Dragging and touch inertia are plain scrolling of .wheel-picker-list
• The 57 reference themes style it as a scroll-snapping list with the chosen option filled and bold

Related components

• listbox
• select
• combobox
• date-time-picker
• slider

References

• WAI-ARIA APG: Listbox
• MDN: CSS scroll snap

Lily™ and Lily Design System™ are trademarks.