Knob
Form-associated rotary knob drawn as a dithered sphere with an arc of lit cells; set it by drag, scroll wheel or arrow keys.
Playground
Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.
<HfKnob
value={7}
min={0}
max={12}
step={0.5}
unit=" dB"
label="Gain"
name="gain"
/>Installation
pnpm dlx shadcn@latest add @lumesec/hf-knobFirst 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}.jsonOr skip the setup and install by URL:
npx shadcn@latest add https://elements.lumesec.ai/r/hf-knob.jsonUsage
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 around the dial, scroll, or use the arrow keys; the value rolls in below.
API reference
Attributes
valueReact propvalueTypenumberDefault50Value, clamped to min–max and snapped to step. Observed: a change moves the knob without events. Also the value a form reset restores.
minReact propminTypenumberDefault0Lower bound. Observed.
maxReact propmaxTypenumberDefault100Upper bound. Observed.
stepReact propstepTypenumberDefault1Step size for drag, wheel and keys; a zero or negative step counts as 1. Its decimal places also set the displayed precision. Observed.
unitReact propunitTypestringText after the displayed value, for example dB. Observed.
labelReact proplabelTypestringDefaultGainText under the value; also the slider aria-label. Observed.
nameReact propnameTypestringForm field name.
disabledReact propdisabledTypebooleanDefaultfalsePresence attribute. The knob ignores pointer, wheel and keys and leaves the tab order; a disabled ancestor <fieldset> does the same. A disabled knob is not submitted.
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
valueTypenumberCurrent value. Setting it clamps and snaps without firing events; it is not reflected to the attribute. A value set before the first connect is kept.
min (read-only)TypenumberParsed min.
max (read-only)TypenumberParsed max.
step (read-only)TypenumberParsed step; a zero or negative step is 1.
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"andaria-labelfromlabel. - Sets
aria-valuenow,aria-valuemin,aria-valuemaxandaria-valuetext(value withunit) on every change. - The visible value text is
aria-hidden. - Pressing on the dial focuses it.
- While disabled, the dial has
aria-disabled="true"andtabindex="-1". - Submits the current value as a string under
name. No validation. Form reset restores thevalueattribute; a disabled knob is not submitted. - 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. All attributes are observed.
Related
Was this page helpful?