Knobs - UI controllers for JS/CSS live manipulation

👉 Demos: Codepen 👈

What is this:

Started as something I needed for my many Codepens - A way to provide viewers, and myself, a set of controllers, for manipulating the DOM instantaneously.

Imagine certain aspects of a web page, or a specific component, which you would like to add the ability to control on-the-fly. Change the visual looks or certain javascript parameters with a move or a slider.

CSS-variables (custom properties) are a great match for this script as they compute in real-time. Javascript is of course a benefitor because every knobs can be attached with a callback that recieves the current value, and additional data, as to what that value should be applied on.

⚠️ Supported only in modern browsers

It's so easy & quick to use Knobs, about 1 minute!

Features:

• Range input (wheel-supported)
• Color input with awesome custom color picker
• Checkbox input
• select dropdown (native)
• Resset all (to defaults)
• Reset individual
• Labels - allows grouping of every knob defined after a label
• Expand/Collapse knobs groups
• Apply change live, on-the-fly, or with an Apply button
• Automatically uses already-declared CSS variables as knobs values, if possible
• Knobs are completely isolated within an iframe (unaffected by page styles)
• Allows 3 states of visibility:
  • Always visible
  • Show on Icon click, Default open
  • Show on Icon click, Default closed
• position of the knobs on the 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.

new Knobs(settings)

Settings

{
  styles      : ``,                // optioanlly add any CSS and it will be injected into the iframe
  flow        : 'horizontal',      // use 'compact' to keep things tight
  position    : 'top right',
  primaryColor: '#0366D6',         // mainly for links / range sliders
  backgroud   : "rgba(0,0,0,1)",
  textColor   : "#CCC",
  border      : 'none'
}

var myKnobs = new Knobs({ CSSVarTarget:document.body }) // only if working with CSS variables

myKnobs.knobs = [{...}, ...] // see example further down
myKnobs.render()

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

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

display: var(--hide, block);

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

Install:

npm i @yaireo/Knobs

CDN source:

https://unpkg.com/@yaireo/[email protected]

Example:

When Using with NPM, first import Knobs

import Knobs from '@yaireo/knobs'

Defining Knobs:

var settings = {
  theme: {
    position: 'bottom right', // default is 'top left'
  },

  // should update immediately (default true)
  live: false,

  // 0 - starts as hidden, 1 - starts as visible, 2 - always visible
  visible: 0,

  CSSVarTarget: document.querySelector('.testSubject'),

  knobs: [
    {
      cssVar: ['width', '-px'], // prefix unit with '-' makes it only a part of the title but not of the variable
      label: 'Width',
      type: 'range',
      value: 200,
      min: 0,
      max: 500,
      step: 50,
      onChange: console.log  // javascript callback on every "input" event
    },
    {
      cssVar: ['width', '-px'],
      label: 'Width preset',
      type: 'select',
      options: [20, 150, [200, '200 nice pixels'], 500],
      value: 150, // should be one of the options
      defaultValue: 150 // value for which to reset to (optional)
      isToggled: false, // this knob will not take affect by default
    },
    {
      cssVar: ['height', 'vh'],
      label: 'Height',
      type: 'range',
      value: 20,
      min: 0,
      max: 100,
      onChange: console.log
    },
    {
      cssVar: ['radius', '%'],
      label: 'Radius of the big square here',
      type: 'range',
      value: 0,
      min: 0,
      max: 50,
      onChange: console.log
    },
    "Label example",
    {
      cssVar: ['bg'], // alias for the CSS variable
      label: 'Color',
      type: 'color',
      value: '#45FDA9',
      onChange: console.log
    },
    {
      cssVar: ['main-bg', null, document.body], // [alias for the CSS variable, units, applies on element]
      label: 'Background',
      type: 'color',
      value: '#FFFFFF',
      onChange: console.log
    },
    ["Label example", false] // group is collapsed by default
    {
      cssVar: ['hide'], // alias for the CSS variable
      label: 'Show',
      type: 'checkbox',
      // checked: true,  // default
      value: 'none',
      onChange: console.log
    },
  ]
}

var penKnobs = new Knobs(settings)