Knob

The Knob component is the root component that handles all the user interactions.

It does not render any visual UI elements but creates a root <div><svg></svg></div>. All children will be added inside this <svg> element.

It handles the user interaction by mouse, mouse wheel and keyboard arrow keys.

It is accessible by keyboard using tab.

The main properties allow to setup the value and the global geometry of the knob.

<Knob
    // hold value
    value={33}
    min={0}
    max={100}
    // geometry
    size={100}
    angleOffset={220}
    angleRange={280}
>
    ...
</Knob>

Value

The knob hold a numeric value. It's an uncontrolled value constained between min and max.

The value can also be set to null. In this case the knob will not show the location.

Geometry

The size is the diameter of the knob. The root <div> is setup with this information as height and width. The knob is defined by the incircle bounded by this square.

angleOffset and angleRange are used to define the location of the begin/end positions. It have to be defined in a radial coordinate, where the 0 is on the top of the knob, and clockwise.

angleOffset is the begin position (when the value is the minimal), and angleRange is the range of the interaction from the begin to the end.angleOffset+angleRange is the end position.

Live Editor

<Knob
    size={100}
    angleOffset={225}
    angleRange={270}
    value={33}
    min={0}
    max={100}
>
    <Arc arcWidth={5} color="#FC5A96" background="#CCCCCC" />
    <Pointer width={5} height={40} radius={10} type="rect" color="#FC5A96" />
</Knob>

Result

Loading...

With this geometry, angleRange can be negative. In this case the interaction became anti clockwise.

Live Editor

<Knob
    size={100}
    angleOffset={135}
    angleRange={-270}
    value={33}
    min={0}
    max={100}
>
    <Arc arcWidth={5} color="#FC5A96" background="#CCCCCC" />
    <Pointer width={5} height={40} radius={10} type="rect" color="#FC5A96" />
</Knob>

Result

Loading...

Properties

Prop	Type	Default	Description
angleOffset	number	0	Offset of the start angle in degree of the knob. The origin 0 in on top and clockwise.
angleRange	number	360	Graphical range of the knob in degree clockwise.
ariaLabelledBy	string		Will be added as aria-labelledby to the knob main element.
ariaValueText	string		Will be added as aria-valuetext to the knob main element.
children	elements		Can be any of knob subcomponents and SVG elements including filter.
className	string		Will be added to the knob main element.
interactiveHook	function		Callback to tune the behaviour of the knob during the mouse interaction. See the details on interactiveHook bellow.
max	number		Max value of the knob.
min	number		Min value of the knob.
multiRotation	boolean	false	If true, the knob can be turned many times. min/max are not taken into acount anymore to limit the value.
onChange	function		Callback that will pass the value when user interact with the knob. If tracking=false this callback is not called during mouse dragging, but is triggered when the mouse is release (if the value have changed)
onEnd	function		Callback triggered when the dragging end.
onInteractiveChange	function		Callback that will pass the value during dragging.
onStart	function		Callback triggered when the dragging start.
readOnly	boolean	false	Indicates if the knob is editable. If true the knob do not react to user input
size	integer		Width and height of the knob in px
snap	boolean	false	Indicates if the knob should snap to a step. Has only an effect if steps is set.
steps	interger		Number of steps the knob can snap to. It's also used to calculate the single steps for the Scale component.
tracking	boolean	true	Control the behaviour of onChange during mouse dragging. If true, onChange is triggered during mouse dragging. If false, onChange is not triggered during mouse dragging, but is triggered when the mouse is release (if the value have changed).
useMouseWheel	boolean	true	Indicates if the knob can be edited with the mouse wheel. If true the knob uses mouse wheel event, and the default wheel event is inhibited. Set to false can prevent to edit the widget during page scroll. Default is true.
value	number	0	Initial value of the knob

interactiveHook

This hook allow to configure the knob to behave in different way depending on the location of the mouse during the interaction.

A dedicated event is passed to this callback during the mouse interaction containing:

• mouseRadius, the radius location of the mouse into the knob
• mouseAngle, the angle (in degree, in range 0..360) location of the mouse into the knob (using the same referential as angleOffset: 0 on top, clockwise)
• mouseX, the X location on the mouse relative to the center of the knob
• mouseY, the Y location on the mouse relative to the center of the knob
• ctrlKey, inherited from MouseEvent
• altKey, inherited from MouseEvent
• metaKey, inherited from MouseEvent
• shiftKey, inherited from MouseEvent

The callback have to return a specific dictionary, which can contain:

• readOnly, if true, the mouse event is inhibited
• steps, number of intervales to snap on

Here is an example of such callback:

function interactiveHook(e) {
    if (e.mouseRadius < 20) {
        // inhibite the center of the knob
        return {readOnly: true}
    }
    // default
    return {}
}