Tweak UI

a lightweight js library for building input controls with data binding.

Installation (NPM)

Install library from NPM

$ npm install tweak-ui
$ yarn add tweak-ui

Then import it in your source code

import * as TweakUi from "tweak-ui"
var TweakUi = require("tweak-ui")

The stylesheet is located at

If you are building a custom stylesheet then finde the SCSS files at

Installation (CDN)

Reference the library and style sheet

Then in your javascript simply use the TweakUI global


Create an HTML container where Tweak UI should render.

Mount the controls. Either by using a builder function

TweakUi.mount(".my-element", (b) => {
  // ... builder function

or an array of control definitions

TweakUi.mount(".my-element", [
  // ... array of control definitions

or a single control definition

TweakUi.mount(".my-element", {
  // ... control definition









an object with spherical coordinates

use a codec to map into 3d vector


an object with 2d coordinates


Object with x, y, z components (default)

2D Vector



The Color control has a format option which describes how the color value should be parsed and encoded. It consists of 2 sections. The prefix specifies whether the color value is a

The suffix specifies the order of the color components. It may be any combinarion of r, g, b and a Here are some examples

format value (r: 255, g: 128, b: 0, a: 1) description
"#rgb" "#FF8000" Hex string with red green and blue coded from left to right
"#bgr" "#0080FF" Hex string with red green and blue coded from right to left
"0xrgb" 16744448 number Hex string with red green and blue coded from right to left
"[]rgb" [255, 128, 0] number array with red green and blue coded from right to left
"{}rgb" { r: 255, g: 128, b: 0 } object red green and blue components
"[n]rgb" [1, 0.5, 0] number array with all components normalized to range [0:1]
"{n}rgb" { r: 1, g: 0.5, b: 0 } object red green and blue components normalized to range [0:1]
Color picker



Display the image as is

Constrain the aspect ratio

Constrain the display width


simple text or html output


A group with a title header

Groups may be collapsible

Nested groups


Renders sub groups as tabs


Automatically handles the collapse state of sub groups


A simple flexbox container. Can be either horizontal or vertical. For more flexibility combine nested containers with custom style rules.


Layout & Labels

The main container has a fixed width of 20rem which is 320px on this page. All controlls are stacked vertically. The default stylesheet uses the flex-box layout model which should render just fine on all modern browsers

Almost all controls have a label to their left side. Hhowever this is only rendered if the label option is actually set. If you want to alignt the controls vertically you have to set the label option at least to an empty string.

Input values

There are several ways how to provide and retreive input values.

Use the value property to set the inital value and then listen for change

Use getters and setters (ECMAScript 5 and above)

Use a target object and provide a property name to get and set the value


This library is based on mithril. All key concepts of mithril also apply to this library. So if you are about to write your own controls for Tweak UI dont forget to check mithrils documentation.

Custom controls

Register your custom controls by using the component function. The argument must be a unique name and a component class or component factory. Consult the documentation of mithriljs for how the components work. Take a look at the source code for how Tweak Ui components are implemented.

Change Theme colors

Tweak ui comes with a default theme and the alternatives .twui-dark and .twui-light. Add one of these classes to the root element to change the look.

this is default

Another quick and easy way is to change the CSS variables for the root element. However not all browsers support that. Read more about CSS variables here , here or here