Skip to content
NewYour data: charts, lists and meters that take your records
<hf-knob>Custom elementControlsForm control

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.

View as Markdown
<hf-knob>

Trydrag around the dial 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
valuelive
minlive
maxlive
steplive
unitlive
labellive
nameremounts
disabledremounts
<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 around the dial, scroll, or use the arrow keys; the value rolls in below.

API reference

Attributes

valueReact propvalueTypenumberDefault50

Value, clamped to min–max and snapped to step. Observed: a change moves the knob without events. Also the value a form reset restores.

minReact propminTypenumberDefault0

Lower bound. Observed.

maxReact propmaxTypenumberDefault100

Upper bound. Observed.

stepReact propstepTypenumberDefault1

Step size for drag, wheel and keys; a zero or negative step counts as 1. Its decimal places also set the displayed precision. Observed.

unitReact propunitTypestring

Text after the displayed value, for example dB. Observed.

labelReact proplabelTypestringDefaultGain

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

nameReact propnameTypestring

Form field name.

disabledReact propdisabledTypebooleanDefaultfalse

Presence 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

valueTypenumber

Current 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)Typenumber

Parsed min.

max (read-only)Typenumber

Parsed max.

step (read-only)Typenumber

Parsed step; a zero or negative step is 1.

Keyboard

KeysAction
ArrowUp / ArrowRightIncrease by one step.
ArrowDown / ArrowLeftDecrease by one step.
PageUp / PageDownChange by five steps.
Home / EndJump 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.
  • While disabled, the dial has aria-disabled="true" and tabindex="-1".
  • Submits the current value as a string under name. No validation. Form reset restores the value attribute; 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.

Was this page helpful?