Knob

An unstyled circular dial component for numeric input with SVG-based rendering.

Build fully custom circular dial controls with complete control over layout and styling.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Knob with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with four sub-components: Root, Range, Value, Text
SVG-based arc rendering with computed paths
Mouse drag, touch drag, and click-to-set interaction
Full keyboard navigation (arrows, Home, End, PageUp, PageDown)
Configurable min, max, step, size, and stroke width

Usage#

import { Knob } from 'primereact/knob';

<Knob.Root>
    <Knob.Range />
    <Knob.Value />
    <Knob.Text />
</Knob.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered element.

<Knob.Root as="section"></Knob.Root>

Default elements: Root=div, Range=path, Value=path, Text=text. The SVG container is rendered automatically by Root.

Render Function Children#

Knob.Text accepts a render function as children, providing access to the component instance for custom value formatting.

<Knob.Text>{(instance) => <>{instance.knob?.state.value}%</>}</Knob.Text>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

/* Select a part to see its CSS selector for custom styling */

API#

KnobRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: KnobRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: KnobRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`KnobRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<KnobRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: KnobRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`defaultValue`	`number`	—
Value of the knob.
`value`	`number`	—
The default value of the knob.
`size`	`number`	`100`
Size of the component in pixels.
`step`	`number`	`1`
Step factor to increment/decrement the value.
`min`	`number`	`0`
Mininum boundary value.
`max`	`number`	`100`
Maximum boundary value.
`strokeWidth`	`number`	`14`
Width of the knob stroke.
`rangeColor`	`string`	—
Background color of the range arc.
`valueColor`	`string`	—
Background color of the value arc.
`textColor`	`string`	—
Color of the value text.
`tabIndex`	`number`	`0`
Index of the element in tabbing order.
`invalid`	`boolean`	—
When present, it specifies that the component should have invalid state style.
`disabled`	`boolean`	—
When present, it specifies that the component should be disabled.
`readOnly`	`boolean`	—
When present, it specifies that the component value cannot be edited.
`ariaLabelledby`	`string`	—
Establishes relationships between the component and label(s) where its value should be one or more element IDs.
`ariaLabel`	`string`	—
Used to define a string that labels the element.
`onValueChange`	`(event: KnobRootChangeEvent) => void`	—
Callback fired when the knob's value changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"knob"`
`data-part`	`"root"`
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only

Defines passthrough(pt) options of Knob component.

label	type	description
root	KnobRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
svg	KnobRootPassThroughType<HTMLAttributes<SVGSVGElement>>	Used to pass attributes to the svg's DOM element.
range	KnobRootPassThroughType<HTMLAttributes<SVGPathElement>>	Used to pass attributes to the range's DOM element.
value	KnobRootPassThroughType<HTMLAttributes<SVGPathElement>>	Used to pass attributes to the value's DOM element.
text	KnobRootPassThroughType<HTMLAttributes<SVGTextElement>>	Used to pass attributes to the text's DOM element.

KnobRange#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: KnobRangeInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: KnobRangeInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`KnobRangeInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<KnobRangePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: KnobRangeInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"knob"`
`data-part`	`"range"`

Defines passthrough(pt) options of KnobRange component.

label	type	description
root	KnobRangePassThroughType<HTMLAttributes<SVGPathElement>>	Used to pass attributes to the root's DOM element.

KnobValue#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: KnobValueInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: KnobValueInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`KnobValueInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<KnobValuePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: KnobValueInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"knob"`
`data-part`	`"value"`

Defines passthrough(pt) options of KnobValue component.

label	type	description
root	KnobValuePassThroughType<HTMLAttributes<SVGPathElement>>	Used to pass attributes to the root's DOM element.

KnobText#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: KnobTextInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: KnobTextInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`KnobTextInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<KnobTextPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: KnobTextInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"knob"`
`data-part`	`"text"`

Defines passthrough(pt) options of KnobText component.

label	type	description
root	KnobTextPassThroughType<HTMLAttributes<SVGTextElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

Knob renders an SVG element with role="slider" and sets aria-valuemin, aria-valuemax, and aria-valuenow to communicate the current state. Provide an accessible name with ariaLabel or ariaLabelledby. When disabled or read-only, the respective aria-disabled and aria-readonly states are applied.

<Knob.Root ariaLabel="Volume" defaultValue={50}></Knob.Root>

If you already render a visible label, connect it using ariaLabelledby.

<span id="volume-label">Volume</span>
<Knob.Root ariaLabelledby="volume-label" defaultValue={50}></Knob.Root>

Keyboard Support#

Key	Function
`tab`	Moves focus to the knob.
`left/down arrow`	Decrements the value.
`right/up arrow`	Increments the value.
`home`	Sets the value to `min`.
`end`	Sets the value to `max`.
`page up`	Increments the value by `10`.
`page down`	Decrements the value by `10`.