rc-knobs
Renders a react knob component that can be widely customised.
Installation
npm install rc-knob
yarn add rc-knob
Examples
https://eskimoblood.github.io/rc-knob/
Usage
The main idea is to split the user interaction and value calculation from the actual rendering of typical knob elements like pointer, scale or value.
So all logic is done in the Knob
component which is the root component.
All visual UI is done in one of this components: Arc
, Pointer
, Scale
and Value
.
All UI elements are rendered as SVG.
All the UI component don't to anything beside rendering and are useless on their own as they need a bunch of props that they get from the parent Knob
component to render the current value of the knob.
A simple knob with a pointer and value would look like this:
import React from 'react'
import { Knob, Pointer, Value } from 'rc-knob'
export default ()=> (
<Knob>
<Value />
<Pointer width={1} height={2}/>
</Knob>
)
API
Knob
The Knob component is root component that handles all the user interactions.
I does not render any visual UI elements but an <div><svg></svg></div>
.
All children will be added to the <svg>
element.
It handles the user interaction by mouse, mouse wheel and keyboard arrow keys.
It is accessible by keyboard using tab
.
Props
angleOffset
Offset of the start angle in degree of the knob.
The default is 0
which will be the top of the circle.
angleRange
Angle of the range in degree. By default its 360.
ariaLabelledBy
Will be added as aria-labelledby
to the knob main element.
ariaValueText
Will be added as aria-valuetext
to the knob main element.
children
Can be any of Arc
, Pointer
, Scale
and Value
.
Also multiple components of the same type can be added.
Beside that, any SVG element including filter
can be rendered.
className
Will be added to the knob main element.
max
Max value of the knob.
min
Min value of the knob.
onChange
Callback that will pass the value when user interact with the knob.
size
Width and height of the knob in px
snap
Indicates if the knob should snap to a step.
Has only an effect if steps
is set.
Is false
be default.
steps
Number of steps the knob can snap to.
It's also used to calculate the single steps for the Scale
component.
value
Value of the knob
Arc
Renders an arc that indicates the current knob value.
Props
arcWidth
Width of the arc. The arc will expand to the centre.
background
Color of the arc over the whole range of the knob.
If background
is not set, the background arc will not rendered.
color
Color of the arc that indicates the value of the knob.
radius
Outer radius of the arc.
Will be the knob size
by default
Pointer
Pointer of the knob.
Can be either be a SVG rect
or circle
depending on the passed type
prop or any SVG element that is passed as a children.
Props
children
Can be any SVG element or a component that will render a SVG element.
If you pass a component the percentage of the current value will be passed as a prop.
The element will be rendered as pointer.
Note, that you have to pass width
and height
as props to make calculate the correct position.
className
Will be added to the rect
, circle
or the children.
color
color
prop passed to the rect
, circle
element if type is selected.
height
Height of the rect
or the custom element.
Will be ignored for circle.
Will be the same as width
if not set.
radius
Outer radius of the circle the pointer sits on.
type
Can be rect
or circle
.
Will render the according SVG element.
width
and|or height
props needs to be set.
width
Width of the rect
or the custom element.
Radius when type is set to circle
.
Scale
Renders a radial scale.
The number of ticks is set by the step
prop of the parent Knob
component.
The single scale tick can be a SVG rect
or circle
.
Additionally a render function can be passed as a prop, that will render each tick.
This is useful if the scale ticks should have different colors, or different tick length for every 10th tick for example.
Props
type
Can be rect
or circle
, default is rect
.
Will render the according SVG element.
tickWidth
and|or tickHeight
props needs to be set.
radius
Outer radius where the ticks ends.
tickWidth
Width of a single tick.
Used as radius if type is circle
.
tickHeight
Height of a single tick.
Is ignored when type is circle
.
color
Will be passed as color prop to the render SVG element of a tick or to the custom render function.
activeColor
color
for the tick that indicates the same value as the current knob value.
className
Will be passed as prop to the render SVG element of a tick or to the custom render function.
activeClassName
className
for the tick that indicates the same value as the current knob value.
fn
Function that can be used to have the full control over how a tick is rendered.
The function needs to return a SVG element.
The function will get the following props passed:
active
,
activeClassName
,
activeColor
,
angleOffset
,
center
,
className
,
color
,
stepSize
,
tickHeight
,
translateX
,
translateY
,
tickWidth
.
Most of them are just passed down from the Pointer
or the Knob
.
Additionally are
center
the half of the size
of the Knob
,
stepSize
the size of the angle of one step in degree,
translateX
, translateY
that are needed to put the tick on the correct position using the transform prop e.g: transform={`translate(${translateX} ${translateY})`}
and i
which is the index of the current tick.
Value
Render the current value as SVG text element.
Props
decimalPlace
Number of decimal places the value should rendered with.
Is 0
by default.
className
className
that is passed to the SVG text
component.
marginBottom
Useful to adjust the horizontal position of the text inside of the Knob
.