Tweak UI

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

Installation (NPM)

Install library from NPM

$ npm install tweak-ui

Import the library (here in typescript)

import * as TweakUi from "tweak-ui"

mount your ui on a DOM element

TweakUi.mount(el, [
  // ... array of definitions

Installation (CDN)

Reference the library and style sheet

Add a container to your HTML

mount your ui on a DOM element

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


get the source at github



Button group





Object with x, y, z components (default)

2D Vector

Arbitrary Keys





2D Pad

an object with 2d coordinates

Direction 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

Custom Control (the lazy way)

simple text or html output





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 registerComponent 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 .tweakui-dark and .tweakui-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