svelte-rc-knob

A highly customizable and accessible knob component for Svelte applications.

Ported from rc-knob originally created by eskimoblood and updated by vallsv.

Overview

The component architecture separates user interaction and value calculation from the visual rendering. This separation allows for maximum flexibility and customization:

• <Knob>: The root component that handles all user interactions and logic
• Visual UI components (all rendered as SVG):
  • <Arc>: Renders the knob's arc
  • <Pointer>: Displays the knob's pointer
  • <Scale>: Shows the knob's scale
  • <Value>: Renders the current value

State Management

The component uses Svelte 5's runes and a dedicated state store created via createKnobState. The <Knob> component provides state and configuration to child components through Svelte's context system with the following structure:

interface KnobContext {
	state: {
		isActive: boolean;
		min: number;
		max: number;
		value: number | null;
		percentage: number | null;
		mouseAngle: number | null;
		startPercentage: number | null;
		startValue: number | null;
		multiRotation: boolean;
		angleOffset: number;
		angleRange: number;
		tracking: boolean;
		size: number;
		steps?: number;
	};
	config: {
		size: number;
		angleOffset: number;
		angleRange: number;
		steps?: number;
	};
}

Child Components

Instead of passing callback functions directly to child components, we use Svelte 5's snippet feature. Each visual component accepts a snippet that receives the necessary props for custom rendering. All components render SVG elements and must be placed within the <Knob>'s SVG container.

Basic Example

<script>
	import { Knob, Pointer, Value } from 'svelte-knob';

	let value = $state(0);
</script>

<Knob bind:value min={0} max={100} size={200}>
	<Value />
	<Pointer width={1} height={2}>
		{#snippet pointer(props)}
			<!-- Custom pointer implementation -->
			<rect {...props} />
		{/snippet}
	</Pointer>
</Knob>

Component API

<Knob>

The root component that handles all user interactions. It renders a <div> with ARIA slider attributes containing an SVG element where all child components are rendered. The knob supports:

• Mouse, scroll wheel, and keyboard arrow key interactions
• Keyboard accessibility via tab
• Two modes of operation:
  • Controlled: using the value prop
  • Uncontrolled: using the initialValue prop

Props

| Prop | Type | Default | Required | Description | | --------------------- | -------- | ------- | -------- | --------------------------------------------------------------------- | | min | number | | Yes | Minimum value | | max | number | | Yes | Maximum value | | size | number | | Yes | Width and height in pixels | | angleOffset | number | 0 | No | Starting angle offset in degrees (0° is at top, clockwise) | | angleRange | number | 360 | No | Total rotation range in degrees (clockwise) | | ariaLabelledBy | string | | No | Sets the aria-labelledby attribute | | ariaValueText | string | | No | Sets the aria-valuetext attribute | | class | string | | No | CSS class for the container div | | svgClass | string | | No | CSS class for the SVG element | | initialValue | number | null | No | Starting value for uncontrolled mode | | value | number | null | No | Current value for controlled mode | | interactiveHook | function | | No | Customizes knob behavior during mouse interaction (see details below) | | multiRotation | boolean | false | No | Enables unlimited rotation (ignores min/max limits) | | onChange | function | noop | No | Callback for value changes (after interaction ends) | | onEnd | function | noop | No | Callback when dragging ends | | onInteractiveChange | function | noop | No | Callback during dragging | | onStart | function | noop | No | Callback when dragging starts | | readOnly | boolean | false | No | Disables user interaction | | snap | boolean | false | No | Enables snapping to steps (requires steps to be set) | | steps | number | | No | Number of snap points | | tracking | boolean | true | No | Controls when onChange fires during dragging | | useMouseWheel | boolean | true | No | Enables mouse wheel interaction |

Interactive Hook

The interactiveHook function allows fine-grained control over knob behavior based on mouse position. It receives an event object with:

interface InteractiveHookEvent {
	mouseRadius: number; // Distance from knob center
	mouseAngle: number; // Angle in degrees (0-360, 0° at top, clockwise)
	mouseX: number; // X position relative to center
	mouseY: number; // Y position relative to center
	ctrlKey: boolean; // Ctrl key state
	altKey: boolean; // Alt key state
	metaKey: boolean; // Meta key state
	shiftKey: boolean; // Shift key state
}

The function should return an object that can include:

interface InteractiveHookResult {
	readOnly?: boolean; // Disables interaction when true
	steps?: number; // Number of snap points
}

Example:

function interactiveHook(e: InteractiveHookEvent): InteractiveHookResult {
	if (e.mouseRadius < 20) {
		return { readOnly: true }; // Disable interaction near center
	}
	return {};
}

<Arc>

Renders an arc showing the current value of the knob. Uses the <Range> component internally to render both the value arc and an optional background arc.

Props

| Prop | Type | Default | Required | Description | | ------------- | ------ | -------------- | -------- | ---------------------------------------------------------------------- | | arcWidth | number | | Yes | Width of the arc in pixels | | percentage | number | context value | No | Current percentage (0-1) to display | | color | string | 'currentColor' | No | Color of the value arc | | background | string | undefined | No | Color of the background arc. If not set, no background arc is rendered | | radius | number | context size/2 | No | Outer radius of the arc in pixels | | class | string | undefined | No | CSS class for the value arc | | activeClass | string | undefined | No | CSS class for the background arc |

<Range>

Low-level component that renders an SVG path representing a range between two percentages. Used internally by the <Arc> component but can also be used directly for custom range visualizations.

The path is generated using SVG arc commands and handles special cases for full circles and tiny angles. It automatically clamps angles to prevent rendering issues at exact 360/-360 degrees.

Props

| Prop | Type | Default | Description | | ---------------- | ------ | -------------- | ---------------------------- | | arcWidth | number | Required | Width of the arc in pixels | | color | string | 'currentColor' | Color of the range arc | | percentage | number | context value | Current percentage value | | percentageFrom | number | null | Starting percentage of range | | percentageTo | number | null | Ending percentage of range | | radius | number | knob size / 2 | Outer radius of the arc | | class | string | '' | CSS class for the range |

The component uses the following logic to determine the actual range to render:

1. If both percentageFrom and percentageTo are provided, uses them directly
2. If only percentageFrom is provided, uses it as start and percentage as end
3. If only percentageTo is provided, uses percentage as start and percentageTo as end
4. If neither is provided, uses 0 as start and percentage as end

<Spiral>

Renders a spiral path between two points with varying radius. Particularly useful for multi-rotation knobs to show winding progression. The spiral is rendered as an SVG path with smooth transitions between points.

Props

| Prop | Type | Default | Description | | ---------------- | ------ | -------------- | ------------------------------------------------- | | arcWidth | number | Required | Width of the spiral line | | color | string | 'currentColor' | Color of the spiral | | percentage | number | context value | Current percentage value | | percentageFrom | number | null | Starting percentage (defaults to 0 or percentage) | | percentageTo | number | null | Ending percentage (defaults to percentage) | | radiusFrom | number | null | Starting radius | | radiusTo | number | null | Ending radius |

The component uses the following logic to determine the actual range:

1. percentageFrom defaults to 0 if percentageTo is set, otherwise uses percentage
2. percentageTo defaults to percentage
3. Both radiusFrom and radiusTo must be provided for the spiral to render

<Pointer>

Visual indicator component that shows the current value of the knob. Supports different shapes and custom SVG elements.

Props

| Prop | Type | Default | Required | Description | | ------------- | ------- | -------------- | -------- | ---------------------------------------------------- | | width | number | | Yes | Width of the pointer | | height | number | width | No | Height of the pointer | | useRotation | boolean | true | No | Use rotation transform instead of position transform | | type | string | | No | Shape type: 'rect', 'circle', or 'triangle' | | color | string | 'currentColor' | No | Fill color of the pointer | | radius | number | size / 2 | No | Distance from center to pointer | | center | number | size / 2 | No | Center point of rotation | | class | string | '' | No | Additional CSS class | | percentage | number | context value | No | Percentage value to display |

Shape Types

• rect: Rectangular pointer centered on rotation point
• circle: Circular pointer with radius equal to width
• triangle: Triangular pointer pointing outward
• Custom: Provided via snippet that receives { width, height, percentage }

Positioning

The pointer can be positioned in two ways, controlled by the useRotation prop:

• true: Rotates pointer around center point using a rotation transform
• false: Positions pointer at calculated x,y coordinates using a translation transform

Example with custom pointer:

<Pointer width={10} height={20}>
	{#snippet pointer({ width, height, percentage })}
		<!-- Custom pointer implementation -->
		<rect x={-width * 0.5} {width} {height} fill="currentColor" />
	{/snippet}
</Pointer>

<Label>

Displays text labels around the knob at specified angles. Labels are positioned in polar coordinates and automatically rotated to maintain readability.

Props

| Prop | Type | Default | Required | Description | | ------------ | ------ | -------------- | -------- | -------------------------------- | | label | string | | Yes | Text to display | | radius | number | | Yes | Distance from center | | percentage | number | | Yes | Position around the circle (0-1) | | center | number | context size/2 | No | Center point | | color | string | 'currentColor' | No | Text color | | class | string | '' | No | CSS class for the text element | | userSelect | string | 'none' | No | CSS user-select property value |

<Scale>

Renders a radial scale with configurable tick marks around the knob. Supports circle and rect tick shapes, or custom rendered ticks.

Props

| Prop | Type | Default | Required | Description | | ------------- | ------ | ------------------------------- | -------- | ----------------------------------- | | tickWidth | number | | Yes | Width of each tick | | tickHeight | number | | Yes | Height of each tick (for rect type) | | type | string | 'rect' | No | Shape type: 'rect' or 'circle' | | radius | number | context size/2 | No | Distance from center to ticks | | color | string | 'currentColor' | No | Default tick color | | activeColor | string | color | No | Color for active tick | | class | string | '' | No | Default tick class | | activeClass | string | class | No | Class for active tick | | steps | number | context steps → prop steps → 10 | No | Number of ticks |

The scale can be customized using a snippet that receives:

interface RenderCustomProps {
	tickWidth: number; // Width of tick
	tickHeight: number; // Height of tick
	translateX: number; // X position
	translateY: number; // Y position
	angleOffset: number; // Starting angle
	stepSize: number; // Angle between ticks
	center: number; // Center point
	color: string; // Default color
	className?: string; // Default class
	active: number; // Index of active tick
	activeColor: string; // Active tick color
	activeClassName: string; // Active tick class
	i: number; // Current tick index
	steps: number; // Total number of steps
	percentage: number; // Current percentage
}

Example with custom ticks:

<Scale tickWidth={2} tickHeight={10}>
	{#snippet custom(props)}
		<!-- Custom tick implementation -->
		<rect
			class={[props.i === props.active ? props.activeClassName : props.className]}
			fill={props.i === props.active ? props.activeColor : props.color}
			stroke="none"
			width={props.tickWidth}
			height={props.tickHeight}
			transform={`
        rotate(${props.angleOffset + props.stepSize * props.i} ${props.center} ${props.center}) 
        translate(${props.translateX} ${props.translateY})
      `}
		/>
	{/snippet}
</Scale>

<Value>

Displays the current value of the knob as text. Supports decimal places formatting and vertical positioning.

Props

| Prop | Type | Default | Required | Description | | -------------- | ------ | -------------- | -------- | ------------------------------ | | value | number | context value | No | Value to display | | radius | number | context size/2 | No | Distance from center | | decimalPlace | number | 0 | No | Number of decimal places | | marginBottom | number | 0 | No | Bottom margin in pixels | | color | string | 'currentColor' | No | Text color | | class | string | '' | No | CSS class for the text element |

The component automatically handles negative zero values by removing the negative sign.

Note: All components require being children of a <Knob> component as they rely on its context for default values and state management.