HyAnglePicker
Usage examples on this page are written for Lit / plain HTML (
<hy-angle-picker>). The same component ships asHyAnglePickerin@whitespaceux/harmony-react(native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.
A circular angle picker for inputs that represent a direction — shadow light angle, gradient direction, hue rotation, anything naturally circular. The control reads as a clock face: cardinal labels around the rim, an indicator line pointing from center to the current angle. Drag the rim, click anywhere inside to snap to that direction, or use arrow keys for fine adjustment. The degrees read beside the dial, so a drag lands near the angle and the arrow keys finish it exactly.
The readout
The number beside the dial is the slider's readout: the value in the locale's digits with suffix after it (the degree sign by default), display-precision decimals (inferred from step when unset), or whatever formatValue returns; hide-value drops it. Its column is reserved for the widest angle so the dial never shifts while dragging. The same string is what a screen reader hears when the needle is off a named tick. A field to type an exact angle stays a hy-number-input beside the dial.
Form Integration
Implements the Form-Associated Custom Elements API — the current angle (in degrees) is included in FormData under name when the containing form submits. A hidden native <input type="range"> inside the shadow root carries the focus, fires change on commit, and surfaces the value to assistive tech via aria-valuetext.
Why a circle, not a slider
Angles are circular: 0° wraps back to itself; there's no real start or end. A linear slider with 0 on the left and 360 on the right fights that mental model — moving from "Left" forward should land back at "Top", not run off the right edge. Every shipping design tool that takes an angle (Figma, Photoshop, Sketch, After Effects, every CSS color wheel for hue) uses a circular control for this reason.
Keyboard
The hidden native range input handles keyboard:
- Arrow keys: ±
step(1° default) - Shift + arrows: ±45° — snap toward the next cardinal
- Home / End: 0° / 180°
- PageUp / PageDown: ±15° (mid-coarse for finer dragging)
Sparse tick marks
Pass tickMarks to label specific compass positions. The picker reuses the slider's TickMark shape so designers learn one vocabulary for "named stops on a numeric range" regardless of the control's geometry. Labels at each angle are auto-positioned on a ring just outside the rim.
When to use
- A direction or a rotation: a gradient angle, a light direction, an image rotation.
Do
- Use
tick-snapwhen only some angles are useful.
When not to use
- People who already know the exact degree:
hy-number-input. Put one beside the dial when both help. - A linear amount such as opacity, size or duration:
hy-slider. A dial says the two ends meet.
Accessibility: your part
- Name the dial with
label, or witharia-labelon the host when the text around it already names it. - Give each entry in
tickMarksalabelor anariaLabel, so keyboard and screen-reader users hear the named direction, not only degrees.
Examples
Basic usage
<hy-angle-picker label="Light angle" value="45"></hy-angle-picker>The readout
The degrees read beside the dial by default. Change the unit, the precision or hide it.
<hy-angle-picker label="Light angle" value="45"></hy-angle-picker>
<hy-angle-picker label="Rotation" value="22.5" step="0.5"></hy-angle-picker>
<hy-angle-picker label="Heading" value="45" suffix=" deg"></hy-angle-picker>
<hy-angle-picker label="Direction" value="90" hide-value></hy-angle-picker>Compass-labeled dial
const picker = document.querySelector('hy-angle-picker');
picker.tickMarks = [
{ value: 0, label: 'T', ariaLabel: 'Top' },
{ value: 90, label: 'R', ariaLabel: 'Right' },
{ value: 180, label: 'B', ariaLabel: 'Bottom' },
{ value: 270, label: 'L', ariaLabel: 'Left' },
];<hy-angle-picker label="Light angle"></hy-angle-picker>Snap-to-cardinals (no diagonals)
picker.tickMarks = [
{ value: 0, label: 'T' },
{ value: 90, label: 'R' },
{ value: 180, label: 'B' },
{ value: 270, label: 'L' },
];<hy-angle-picker label="Direction" tick-snap></hy-angle-picker>Error and warning
Setting error-message raises error: the indicator and the rim take the danger color and the input is marked invalid. warning-message raises warning: the same treatment in the warning color, announced politely, and the value stays valid. error wins when both are set.
<hy-angle-picker
label="Light angle"
value="200"
error-message="Light from below is not supported"
></hy-angle-picker>
<hy-angle-picker
label="Light angle"
value="170"
warning-message="Light from below reads as unnatural"
></hy-angle-picker>Form submission
<form>
<hy-angle-picker name="light-angle" value="135"></hy-angle-picker>
<button type="submit">Save</button>
</form>API
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
value | value | number | 0 | Current angle in compass degrees [0, 360). Values outside this range are wrapped on write. |
step | step | number | 1 | Granularity for keyboard arrow-key adjustments. Default 1° — pointer-driven changes ignore step and operate at pixel precision. |
disabled | disabled | boolean | false | Disables the picker. |
error | error | boolean | false | Error state: the value is not accepted. Paints the indicator and rim in the danger color and sets aria-invalid. |
warning | warning | boolean | false | Warning state: the value is accepted but worth a second look. Paints the indicator and rim in the warning color; never sets aria-invalid and never blocks submission. error wins when both are set. |
name | name | string | '' | The name attribute for form submission. |
label | label | string | '' | Primary label displayed above the dial. |
hint | hint | string | '' | Secondary hint text displayed under the label. |
helperText | helper-text | string | '' | Helper text displayed below the dial. |
errorMessage | error-message | string | '' | Error message shown under the dial (replaces the helper text). Setting it raises error; clearing it lowers it. |
warningMessage | warning-message | string | '' | Warning message shown under the dial (replaces the helper text). Setting it raises warning; clearing it lowers it. |
size | size | 'small' | 'medium' | 'large' | 'medium' | Size variant affecting dial diameter. |
tickMarks | — | TickMark[] | [] | Sparse named tick marks positioned around the rim. Same shape as hy-slider's tickMarks — { value, label?, ariaLabel? }. Property-only (arrays can't round-trip via HTML attribute); set via Lit .tickMarks=${[...]} or framework property binding. See TickMark (re-exported from this module). |
tickSnap | tick-snap | boolean | false | When true, the picker snaps to the values declared in tickMarks during pointer drag — step still governs keyboard granularity. Defaults to false (tick marks are visual references only). No-op when tickMarks is empty. |
suffix | suffix | string | '°' | String appended to the value readout. The degree sign by default. |
hideValue | hide-value | boolean | false | Hides the numeric value readout beside the dial. |
displayPrecision | display-precision | number | undefined | — | Number of decimal places shown in the value readout and aria-valuetext. Leave unset to infer from step (step=0.5 → 1, step=1 → 0). Overridden by formatValue when set. |
formatValue | — | (value: number) => string | undefined | — | Custom formatter for the value readout and aria-valuetext. When set, owns the full display string — suffix is NOT appended and displayPrecision is ignored. Must be a function, so it cannot be set via an HTML attribute; assign it as a property (el.formatValue = fn) or via a framework property binding (.formatValue=${fn} in Lit, formatValue={fn} in React). |
locale | locale | string | undefined | — | BCP-47 locale for the readout's digits and separators. Unset, the nearest lang (across shadow roots), else the browser's language. The value and the form value stay plain numbers. |
inputId | input-id | string | '' | Explicit id for the underlying input; empty uses the fixed input (components.md "Ids"). |
autofocus | autofocus | boolean | false | Marks this picker as the auto-focus target. Read by hy-dialog (and other overlay containers) on show to choose initial focus, and applied to the inner native input on first connect. |
form | — | HTMLFormElement | null | — | — |
validity | — | ValidityState | — | — |
validationMessage | — | string | — | — |
Events
| Event | Detail | Description |
|---|---|---|
input | — | Fired during drag / keyboard adjustment. Detail: { value: number } |
change | — | Fired when the value is committed (pointer release / blur). Detail: { value: number } |
CSS Parts
| Part | Description |
|---|---|
base | The outer wrapper (label + dial + helper text column) |
label | The label container (label + hint) |
row | Row containing the dial and the value readout |
value | The numeric value readout beside the dial |
dial | The clickable circle that owns the rim + indicator + labels |
input | The hidden native range input |
rim | The visible circle border |
indicator | The line from center to the current angle |
thumb | The thumb dot at the tip of the indicator |
hub | The small disc at the center of the dial |
tick-marks | Container for the rim tick lines (only present when tickMarks has entries) |
tick-mark | Individual tick line on the rim |
tick-mark-labels | Container for tick labels positioned around the rim |
tick-mark-label | Individual label outside the rim |
helper-text | The helper text element |
error-message | The error message element |
warning-message | The warning message element |
message-icon | The icon starting the error or warning message |
CSS Custom Properties
The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.
| Property | Default | Description |
|---|---|---|
--hy-angle-picker-size-sm | — | Dial diameter for size=small. Default: 4.5rem |
--hy-angle-picker-size-md | — | Dial diameter for size=medium. Default: 6.5rem |
--hy-angle-picker-size-lg | — | Dial diameter for size=large. Default: 9rem |
--hy-angle-picker-border-default-rest | var(--hy-border-default-rest) | Rim stroke color |
--hy-angle-picker-border-danger-rest | var(--hy-border-danger-rest) | Rim stroke color |
--hy-angle-picker-border-warning-rest | var(--hy-border-warning-rest) | Rim stroke color |
--hy-angle-picker-rim-stroke-md | var(--hy-stroke-md) | Rim stroke width |
--hy-angle-picker-fill-color | transparent | Optional fill behind the indicator (defaults to transparent) |
--hy-angle-picker-background-brand-indicator-rest | var(--hy-background-brand-indicator-rest) | Color of the indicator line + hub |
--hy-angle-picker-background-danger-indicator-rest | var(--hy-background-danger-indicator-rest) | Color of the indicator line + hub |
--hy-angle-picker-background-warning-indicator-rest | var(--hy-background-warning-indicator-rest) | Color of the indicator line + hub |
--hy-angle-picker-indicator-stroke-md | var(--hy-stroke-md) | Indicator stroke width |
--hy-angle-picker-hub-ornament-bullet | var(--hy-ornament-bullet) | Diameter of the center disc |
--hy-angle-picker-hub-ornament-tick | var(--hy-ornament-tick) | Diameter of the center disc |
--hy-angle-picker-hub-ornament-handle | var(--hy-ornament-handle) | Diameter of the center disc |
--hy-angle-picker-thumb-ornament-handle | var(--hy-ornament-handle) | Diameter of the draggable disc at the indicator tip |
--hy-angle-picker-thumb-ornament-bullet | var(--hy-ornament-bullet) | Diameter of the draggable disc at the indicator tip |
--hy-angle-picker-thumb-ornament-pellet | var(--hy-ornament-pellet) | Diameter of the draggable disc at the indicator tip |
--hy-angle-picker-tick-foreground-subtle-rest | var(--hy-foreground-subtle-rest) | Color of rim tick lines (only when tickMarks is set) |
--hy-angle-picker-tick-label-foreground-subtle-rest | var(--hy-foreground-subtle-rest) | Color of rim tick labels |
--hy-angle-picker-value-foreground-subtle-rest | var(--hy-foreground-subtle-rest) | Value readout color |
--hy-angle-picker-value-width | — | Minimum width of the value readout column (measured from the widest angle by default) |
--hy-angle-picker-foreground-danger-rest | var(--hy-foreground-danger-rest) | Error message text and icon color |
--hy-angle-picker-foreground-warning-rest | var(--hy-foreground-warning-rest) | Warning message text and icon color |
--hy-angle-picker-gap-layout-2xs | var(--hy-gap-layout-2xs) | Gap between the message icon and its text |
--hy-angle-picker-label-radius | — | Radial distance from center to the nearest edge of each tick label. Default: dial radius + 0.25em |
--hy-angle-picker-motion-transition-hover-duration | var(--hy-motion-transition-hover-duration) | Transition duration for hover and focus state feedback |
--hy-angle-picker-motion-transition-hover-easing | var(--hy-motion-transition-hover-easing) | Transition easing for hover and focus state feedback |
--hy-angle-picker-thumb-ring-color | — | Ring around the thumb (follows the indicator color) |