<rotary-input>

A rotating knob form input with scaling, ticks, units and formatted output display.

Pan

Volume

Frequency

Import

Import and register the <rotary-input> custom element, upgrading any instances already in the DOM:

import RotaryInput from '../../literal/documentation/templates/rotary-input.js';

Use

You can now author rotating knob inputs:

<rotary-input name="pan" min="-1" max="1" ticks="-1 -0.8 -0.6 -0.4 -0.2 0 0.2 0.4 0.6 0.8 1">Pan</rotary-input>
<rotary-input name="gain" min="0" max="2" ticks="-∞dB -48dB -42dB -36dB -30dB -24dB -18dB -12dB -6dB 0dB 6dB" law="log-48dB" display="dB" value="-6dB">Volume</rotary-input>
<rotary-input name="frequency" min="20" max="20000" ticks="20Hz 30Hz 50Hz 100Hz 200Hz 300Hz 500Hz 1kHz 2kHz 3kHz 5kHz 10kHz 20kHz" law="log" display="Hz" value="1000">Frequency</rotary-input>

Attributes

value

The initial value of the input.

wrap

Boolean attribute indicating whether rotation is continuous and value ‘wraps’ around.

min ="0"

Value at lower limit of fader. Will interpret string values with recognised units, eg. "0dB" or "200Hz", or numbers.

max ="1"

Value at upper limit of fader. Will interpret string values with recognised units, eg. "0dB" or "200Hz", or numbers.

law ="linear"

Fader law. This is the name of a transform to be applied over the range of the fader travel. Possible values are:

"linear"
"quadratic"
"cubic"
"log"
"log-24dB"
"log-48dB"
"log-60dB"
"log-72dB"
"log-96dB"

ticks

A space or comma separated list of values at which to display tick marks. Values may be listed with or without units, eg:

ticks="0 0.2 0.4 0.6 0.8 1"
ticks="-∞dB -48dB -36dB -24dB -12dB 0dB"

Note that the unicode ∞ infinity character is interpreted as Infinity (after unit conversion -∞dB is 0 and 0dB is 1).

Ticks may optionally be given labels, displayed in lieu of the tick value. Labels are written in square brackets following the tick value:

ticks="0 [None] 0.5 [Half] 1 [Full]"

display

The units to display the value in. The output value and all ticks are displayed in this unit. Possible values are:

"dB" – 0-1 is displayed as -∞dB to 0dB
"Hz" - frequency in Hz and kHz
"bpm" - displays rates in Hz as bpm
"s" - time in ms and s
"semitone" - without units
"hh:mm" – and other time formats including any of the tokens YMwdhms

Display formatters may be added by importing the formatters object:

RangeInput.displayFormats['my-format'] = (format, value) => {
    // Return an object of the form `{ value, unit }`
};

This format may now be used by declaring the display attribute:

display="my-format"

step

Step is either:

"any", the default value
"ticks", the values in the ticks attribute are used as step values
A space or comma separated list of values, with or without units

Properties

.value

Current value of the input.

.wrap

Boolean indicating whether rotation is continuous and value ‘wraps’ around.

.type

“number” A readonly property with the value "number" (provided for consistency with native form elements, which all have a type).

.min

Value at lower limit of fader. Will interpret string values with recognised units, eg. "0dB" or "200Hz", or numbers.

.max

Value at upper limit of fader. Will interpret string values with recognised units, eg. "0dB" or "200Hz", or numbers.

Events

"input"

Emitted from the element during the movement of a handle.

"change"

Emitted from the element when a handle has been moved.

Parts

::part(tick)

Style the tick marks.

::part(output)

Style the display of the output value.

Variables

--value-color

--value-color-start

--value-color-end

--handle-color

--handle-background

--handle-border

--output-color

--track-background

--track-padding

Make the range input slightly wider than the control to allow range thumb to line up with label text.

--handle-size

--handle-shadow

--track-width

--track-shadow

--rotation-start

Angle (clockwise from south) at which to start rotational travel.

--rotation-range

Angle (clockwise from south) through which handle travels.

--touch-range

Vertical distance of mouse or touch movement that results in one full range of rotation of the handle. Cannot be specified as a % length, other length units accepted..

Built by Stephen Band for Cruncher.

Documentation set in Euclid and Martian Mono. Fonts used for documentation not included as part of the license covering the use of rotary-input.