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
node_modules/tweak-ui/tweak-ui.css

If you are building a custom stylesheet then finde the SCSS files at
node_modules/tweak-ui/scss

Installation (CDN)

Reference the library and style sheet

Then in your javascript simply use the TweakUI global

Usage

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
})

Controls

Number

Slider

Text

Checkbox

Select

Angle

Spherical

an object with spherical coordinates

use a codec to map into 3d vector

Point

an object with 2d coordinates

Position

Object with x, y, z components (default)

2D Vector

Array

Color

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

Button

Image

Display the image as is

Constrain the aspect ratio

Constrain the display width

Content

simple text or html output

Group

A group with a title header

Groups may be collapsible

Nested groups

Tabs

Renders sub groups as tabs

Accordion

Automatically handles the collapse state of sub groups

Container

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

Concepts

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

Mithril

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
.twui-dark
.twui-light

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

Comments