Knob

Adjust a bounded numeric value with a circular control.

Category: Forms and selection
Import: @neural-ui/core/knob
Selector: neu-knob

import { NeuKnobComponent } from '@neural-ui/core/knob';

Usage

Use min, max and step to define the accepted scale and keep min below max. size is the diameter in pixels; showValue hides only the visual number. Give the control an accessible name and use valueText when the numeric value needs units.

Examples

Try this application-owned interaction. Its event handling and initial data are included in Code.

Volume

Current value: 40

Events: 0

Try and configure

Change the public options, try the result and inspect the updated template. Code contains the complete executable implementation.

Volume

Current value: 40

Events: 0

disabled

readonly

invalid

min

max

step

size

showValue

Advanced options · 11

<neu-knob
  (valueChange)="onValueChange($event)"
  [disabled]="false"
  [readonly]="false"
  [invalid]="false"
  [min]="0"
  [max]="100"
  [step]="5"
  [size]="96"
  [showValue]="true"
  [ariaLabel]="'Volume'"
  [label]="'Volume'"
  [value]="40"
/>

Data, callback and structured configuration inputs

These inputs require a model or function, not a checkbox. Edit the same-named field in the Source component and bind it in the template; data already used by this preview appears in the state above.

errors · readonly ValidationError.WithOptionalFieldTree[]

In Source: define errors with this type and use [errors]="errors" (or errors() for a signal).

valueText · ((value: number) => string) | undefined

In Source: define valueText with this type and use [valueText]="valueText" (or valueText() for a signal).

State and events

Accessibility and keyboard

Focus the slider with Tab. Arrow keys adjust by step; Home/End reach the bounds. Disabled and readonly values cannot be edited.

Key	Action
`Tab`	Focus the control when enabled.
`ArrowUp / ArrowRight`	Increase the value by step, unless readonly.
`ArrowDown / ArrowLeft`	Decrease the value by step, unless readonly.
`Home`	Set the minimum value when editing is allowed.
`End`	Set the maximum value when editing is allowed.

API

Inputs, models and Outputs are extracted from the installed Core package. Named public types link to their definitions. Templates below include executable examples.

Inputs

Configure the component with [property]="value". Your application supplies these values; the component does not replace the state you pass in.

Name	Type	Default	Template binding	Description
`ariaDescribedBy`	`string`	`''`	`[ariaDescribedBy]`	IDs of elements describing the control, separated by spaces.
`ariaLabel`	`string`	`''`	`[ariaLabel]`	Accessible name of the control or region.
`dirty`	`boolean`	`false`	`[dirty]`	Form state indicating that the user has changed the value.
`disabled`	`boolean`	`false`	`[disabled]`	Prevents interaction with this control.
`errors`	`readonly ValidationError.WithOptionalFieldTree[]`	`[]`	`[errors]`	Validation errors supplied by the form or the application.
`hidden`	`boolean`	`false`	`[hidden]`	Hides the control according to the form state.
`inputId`	`string`	`inject(NeuIdGenerator).getId('neu-knob-')`Derived default	`[inputId]`	Stable control id, generated when omitted; use it to associate labels or descriptions.
`invalid`	`boolean`	`false`	`[invalid]`	Displays the invalid state; it does not add a validation rule.
`label`	`string`	`''`	`[label]`	Visible label naming the field or action.
`max`	`number \| undefined`	`100`	`[max]`	Upper numeric bound.
`min`	`number \| undefined`	`0`	`[min]`	Lower numeric bound.
`name`	`string`	`''`	`[name]`	Name of the form control.
`pending`	`boolean`	`false`	`[pending]`	Form state indicating that asynchronous validation is pending.
`readonly`	`boolean`	`false`	`[readonly]`	Keeps the applied value visible but prevents user edits.
`required`	`boolean`	`false`	`[required]`	Marks the field as required; use a form validator to enforce it.
`showValue`	`boolean`	`true`	`[showValue]`	Shows the numeric value inside the knob.
`size`	`number`	`80`	`[size]`	Control diameter in pixels.
`step`	`number`	`1`	`[step]`	Positive increment used when adjusting the numeric value.
`touched`	`boolean`	`false`	`[touched]`	Form state indicating that the control has been visited.
`valueText`	`((value: number) => string) \| undefined`	`undefined`	`[valueText]`	Function that converts the numeric value to accessible text, such as a value with units.

Models

A model supports [(property)]="signal" or the [property] and (propertyChange) pair. Choose one form, not both.

Name	Type	Default	Template binding	Description
`value`	`number`	`0`	`[(value)]`	Applied numeric value within the configured range.

Outputs

Listen to an event with (event)="handler($event)". The table explains the data your handler receives and how to use it.

Name	Payload	Template binding	Description
`touch`	`void`	`(touch)="onTouch($event)"`	Notifies the form that the control has been touched; not a value change.

Templates

ng-content projects content into the component. TemplateRef inputs receive a template; ng-template directives identify templates with a typed context. A directive shared by an entrypoint is not necessarily a slot of this component.

This component does not expose content projection or public customization templates.

Styles and tokens

Use the supported public tokens listed below. Surrounding layout belongs to your application; validate the result in light and dark modes and narrow containers.

Specific tokens

Token	Purpose	State / variant	Default / source	Fallback
`--neu-knob-display-color`	Inherited theme value used by this component	Field surface	`var(--neu-text)`Root declaration	`--neu-text`
`--neu-knob-label-color`	Inherited theme value used by this component	Field surface	`var(--neu-text-muted)`Root declaration	`--neu-text-muted`
`--neu-knob-track`	Inherited theme value used by this component	Field surface	`var(--neu-surface-3)`Root declaration	`--neu-surface-3`

Shared tokens used

Override these on a local wrapper to affect this example. An override on :root affects other components that use the same token.

Token	Purpose here	Other impact	Default / fallback
`--neu-focus-ring`	Normal keyboard-focus ring	Shared by other Core consumers; scope the override.	`0 0 0 var(--neu-focus-ring-width) rgba(0, 122, 255, 0.15)`
`--neu-primary`	Brand color for active controls and emphasis	Shared by other Core consumers; scope the override.	`#007aff`
`--neu-text`	Main text and inherited icon color	Shared by other Core consumers; scope the override.	`#0f172a`
`--neu-text-muted`	Secondary labels and supporting content	Shared by other Core consumers; scope the override.	`#475569`
`--neu-border-color`	Inherited theme value used by this component	Shared by other Core consumers; scope the override.	`var(--neu-border)`