Knob · Pixel HD component · LumeSec Elements

<hf-knob>· loading

Trydrag vertically or scroll over it.

Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

Loading <hf-knob>

Props

valueremounts

minremounts

maxremounts

stepremounts

unitremounts

labelremounts

nameremounts

<HfKnob
  value={7}
  min={0}
  max={12}
  step={0.5}
  unit=" dB"
  label="Gain"
  name="gain"
/>

Installation

pnpm dlx shadcn@latest add @lumesec/hf-knob

First timeRegister the @lumesec registry once, or install by URL+

Adds @lumesec to your components.json:

pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json

Or skip the setup and install by URL:

npx shadcn@latest add https://elements.lumesec.ai/r/hf-knob.json

Usage

import { HfKnob } from "@/components/lumesec/hf-knob";

export function Example() {
  return (
    <HfKnob name="gain" label="Gain" min={0} max={12} step={0.5} value={7} unit=" dB" />
  );
}

Behaviour

A dithered sphere with an arc of lit cells. Drag up or down, scroll, or use the arrow keys; the value rolls in below.

API reference

Attributes

valueReact propvalueTypenumberDefault50

Initial value, clamped to min–max and snapped to step. Read once on connect.

minReact propminTypenumberDefault0

Lower bound.

maxReact propmaxTypenumberDefault100

Upper bound.

stepReact propstepTypenumberDefault1

Step size for drag, wheel and keys. Its decimal places also set the displayed precision.

unitReact propunitTypestring

Text after the displayed value, for example dB.

labelReact proplabelTypestringDefaultGain

Text under the value; also the slider aria-label.

nameReact propnameTypestring

Form field name.

Events

Events bubble and cross the shadow boundary unless the description says otherwise.

inputReact proponInputDetail{ value: number }

Fires on every value change from drag, wheel or keys.

changeReact proponChangeDetail{ value: number }

Fires on pointer release and on each wheel step or key press.

Properties

valueTypenumber

Current value. Setting it clamps and snaps without firing events; it is not reflected to the attribute.

min (read-only)Typenumber

Parsed min.

max (read-only)Typenumber

Parsed max.

step (read-only)Typenumber

Parsed step.

Keyboard

Keys	Action
ArrowUp / ArrowRight	Increase by one step.
ArrowDown / ArrowLeft	Decrease by one step.
PageUp / PageDown	Change by five steps.
Home / End	Jump to `min` or `max`.

Accessibility

The canvas has role="slider", tabindex="0" and aria-label from label.
Sets aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext (value with unit) on every change.
The visible value text is aria-hidden.
Pressing on the dial focuses it.
Submits the current value as a string under name. No validation; form reset does not change the value.
Reduced motion: the indicator and arc jump to the value without the spring and the value text swaps without rolling.

Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from --lumesec. See Theming.

This component reads --foreground, --lumesec and --muted-foreground.

To restyle only LumeSec elements, set the matching --ui-* overrides: --ui-accent, --ui-fg and --ui-muted.

Notes

Dragging sets the value from the pointer angle around the centre over a 270° sweep; it is not a vertical drag.
The wheel handler calls preventDefault(), so scrolling over the knob does not scroll the page.
The dial is fixed at 200 × 200 px. Attributes are not observed.

<hf-button>

Buttonhf-button

<hf-switch>

Switchhf-switch

<hf-segmented>

Segmented controlhf-segmented

<hf-input>

Text fieldhf-input

Related