Knobs 🎛️ UI controllers for JS/CSS manipulation

👉 Demo 👈

Features:

• range input (wheel-supported)
• color input with awesome custom color picker
• checkbox input
• radio inputs group
• select dropdown (native)
• Custom HTML-Knobs (add your own buttons or whatever)
• Resset all knobs (to defaults)
• Reset individual knob
• Labels - group all the knobb defined after a certain label
• Expand/Collapse knobs groups
• Apply changes live, on-the-fly, or with an Apply button
• Auto-detect CSS variables defined in knobs as their initialvalues, if possible
• Knobs are completely isolated within an iframe (unaffected by your page styles)
• Allows 3 states of visibility:
  • 0 - Starts as hidden
  • 1 - Starts as visible
  • 2 - Always visible
• Knobs component placement position (relative to window viewport):
  • top right (default)
  • bottom right
  • top left
  • bottom left
• Allows theme customization (currently very limited)

Configuration:

All is needed is to include the knobs script on the page, and set it up.

1new Knobs(settings)

Settings

1{
2  styles      : ``,                // optioanlly add any CSS and it will be injected into the iframe
3  flow        : 'horizontal',      // use 'compact' to keep things tight
4  position    : 'top right',
5  primaryColor: '#0366D6',         // mainly for links / range sliders
6  'base-color': "rgba(0,0,0,1)",   // mainly for the background color but also for input fields such as text or number
7  textColor   : "#CCC",
8  border      : 'none'
9}

1var myKnobs = new Knobs({ CSSVarTarget:document.body }) // only if working with CSS variables
2
3myKnobs.knobs = [{...}, ...] // Add/change the knobs. will automatically re-render (see example further below)

1div{
2  --size: 10;
3  /* limits with width to a minimum of 10px by using unitless variable for the "max" function */
4  width: calc(Max(50, var(--size)) * 1px);
5}

1{

2  cssVar: ['main-color'],

3  cssVarsHSLA: true,

4  label: 'Page background',

5  type: 'color',

6  defaultFormat: 'hsla',
7},

1{
2  cssVar: ['hide'], // CSS variable name "--hide"
3  label: 'Show',
4  type: 'checkbox',
5  // checked: true,  // not checked by default
6  value: 'none', // if checked: --hide: none;
7}

1display: var(--hide, block);

[20, 150, [200, '200 nice pixels'], 500]

1{
2  render: `
3    <button onclick='alert(1)'>1</button>
4    <button onclick='alert(2)'>2</button>
5  `,
6  knobClass: 'custom-actions'
7}

1{
2  label: 'Custom HTML with label',
3  render: `
4    <button type='button' class='specialBtn1'>1</button>
5    <button type='button' class='specialBtn2'>2</button>
6  `,
7  script(knobs, name){
8    knobs.getKnobElm(name).addEventListener("click", e => {
9      if( e.target.tagName == 'BUTTON' )
10        alert(e.target.textContent)
11    })
12  },
13},

Install:

npm i @yaireo/knobs

CDN source:

https://unpkg.com/@yaireo/knobs@latest

Example:

When Using with NPM, first import Knobs

1import Knobs from '@yaireo/knobs'

Color manipulation methods:

format & CSStoHSLA are defined on Knobs' instances in color property, for example:

1const myKnobs = new Knobs({
2  ...,
3  knobs: [
4    {
5      cssVar: ['bg'], // alias for the CSS variable
6      label: 'Color',
7      type: 'color',
8      value: '#45FDA9',
9      onChange(e, knobData, hsla) => {
10        console.log( myKnobs.format(knobData.value, 'rgb') )  // will print a color string in RGBA
11      }
12    }
13  ]
14})
15
16myKnobs.color.format()

See color-picker docs

Defining Knobs:

1var settings = {
2  theme: {
3    position: 'bottom right', // default is 'top left'
4  },
5
6  // should update immediately (default true)
7  live: false,
8
9  // 0 - starts as hidden, 1 - starts as visible, 2 - always visible
10  visible: 0,
11
12  CSSVarTarget: document.querySelector('.testSubject'),
13
14  knobs: [
15    {
16      cssVar: ['width', '-px'], // prefix unit with '-' makes it only a part of the title but not of the variable
17      label: 'Width',
18      labelTitle: 'Changes the width at steps of 50 pixels',
19      type: 'range',
20      value: 200,
21      min: 0,
22      max: 500,
23      step: 50,
24      onChange: console.log  // javascript callback on every "input" event
25    },
26
27    {
28      cssVar: ['width', '-px'],
29      label: 'Width preset',
30      type: 'select',
31      options: [20, 150, [200, '200 nice pixels'], 500],
32      value: 150, // should be one of the options
33      defaultValue: 150 // value for which to reset to (optional)
34      isToggled: false, // this knob will not take affect by default
35    },
36
37    {
38      cssVar: ['height', 'vh'],
39      label: 'Height',
40      type: 'range',
41      // value: 20,  // if a value is not defined, Knobs will try to get it from the CSS ("CSSVarTarget" selector) automatically
42      min: 0,
43      max: 100,
44      onChange: console.log
45    },
46
47    {
48      cssVar: ['align'],
49      label: 'Align boxes',
50      type: 'radio',
51      name: 'align-radio-group',
52      options: [
53        { value:'left', hidden:true, label: '<svg ...' },
54        { value: 'center', label:'Center' },
55        { value:'right', hidden:true, label:'<svg ...' }
56      ],
57      value: 'center',
58      defaultValue: 'left'
59    },
60
61    {
62      cssVar: ['radius', '%'],
63      label: 'Radius of the big square here',
64      type: 'range',
65      value: 0,
66      min: 0,
67      max: 50,
68      onChange: console.log
69    },
70
71    "Label example",
72
73    {
74      cssVar: ['bg'], // alias for the CSS variable
75      label: 'Color',
76      type: 'color',
77      defaultFormat: 'hsla',
78      cssVarsHSLA: true,
79      value: '#45FDA9',
80      swatches: ['red', 'gold'],  //  swatches which can be selected inside the color picker
81      onChange: (e, knobData, hsla) => console.log(e, knobData, hsla, knobData.value)
82    },
83
84    {
85      cssVar: ['main-bg', null, document.body], // [alias for the CSS variable, units, applies on element]
86      label: 'Background',
87      type: 'color',
88      value: '#FFFFFF',
89      onChange: (e, knobData, hsla) => console.log(e, knobData, hsla, knobData.value)
90    },
91
92    ["Label example", false] // group is collapsed by default
93    {
94      cssVar: ['hide'], // alias for the CSS variable
95      label: 'Show',
96      type: 'checkbox',
97      // checked: true,  // default
98      value: 'none',
99      onChange: console.log
100    },
101
102    {
103      label: 'Custom with label',
104      render: `
105        <button type='button' class='specialBtn1'>1</button>
106        <button type='button' class='specialBtn2'>2</button>
107      `,
108      script(knobs, name){
109        knobs.getKnobElm(name).addEventListener("click", e => {
110          if( e.target.tagName == 'BUTTON' )
111            alert(e.target.textContent)
112        })
113      },
114    },
115
116    {
117      render: `
118        <button type='button' class='specialBtn3'>😎</button>
119      `,
120      script(knobs){
121        const elm = knobs.DOM.scope.querySelector('.specialBtn3')
122        elm.addEventListener("click", () => alert('😎'))
123      },
124      knobClass: 'custom-actions'
125    }
126  ]
127}
128
129var penKnobs = new Knobs(settings)