settings-panel
Simple settings panel for your app, demo or tests.
In the preview there is a typer theme, for other themes or customizations see demo.
Usage
var createPanel = require('settings-panel')
var panel = createPanel([
{type: 'range', label: 'my range', min: 0, max: 100, value: 20},
{type: 'range', label: 'log range', min: 0.1, max: 100, value: 20, scale: 'log'},
{type: 'text', label: 'my text', value: 'my cool setting', help: 'why this is cool'},
{type: 'checkbox', label: 'my checkbox', value: true},
{type: 'color', label: 'my color', format: 'rgb', value: 'rgb(10,200,0)', change: value => console.log(value)},
{type: 'button', label: 'gimme an alert', change: () => alert('hello!')},
{type: 'select', label: 'select one', options: ['option 1', 'option 2'], value: 'option 1'}
],
{
title: 'Settings',
style: 'position: absolute; right: 0; z-index: 1'
}
);
API
const Panel = require('settings-panel')
let panel = new Panel(fields, options?)
The first argument is a list of fields or object with id/field pairs. Each field may have following properties:
-
type
one ofrange
β’interval
β’checkbox
β’color
β’select
β’switch
β’raw
β’textarea
β’text
or any<input>
type. If undefined, type will be detected from the value. -
id
used as key to identify the field. If undefined, the label will be used instead. -
label
label for the input. If label is false, it will be hidden. -
value
current value of the field. -
default
explicitly defines default value, if differs from the initial value. -
orientation
defines position of a label relative to the input, one oftop
,left
,right
,bottom
. Redefinesoptions.orientation
. -
style
appends additinal style to the field, can be a css object or css string. -
hidden
defines whether field should be visually hidden, but present as a value. -
disabled
just disables the input, making it inactive. -
input
callback, invoked if value changed. -
init
invoked once component is set up. -
change
invoked each time the field value changed, whether throughinput
or API. -
before
andafter
define an html to display before or after the element, can be a string, an element or a function returning one of the two. That may come handy in displaying help, info or validation messages, separators, additional buttons, range limits etc - anything related to the element. -
title
will display text in tooltip.
For example,
{type: 'checkbox', label: 'My Checkbox', value: true, input: value => {}}
Some types have additional properties:
-
range
can specify amin
,max
, andstep
(or integersteps
). Scale can be either'linear'
(default) or'log'
. If a log scale, the sign ofmin
,max
, andvalue
must be the same and onlysteps
is permitted (since the step size is not constant on a log scale). It also takesprecision
optional parameter for the displayed value. -
interval
obeys the same semantics asrange
inputs, except the input and ouput is a two-element array corresponding to the low/high bounds, e.g.value: [1, 7.5]
. -
color
can specify aformat
as eitherrgb
β’hex
β’array
-
select
,switch
andcheckbox
can specifyoptions
, either as anArray
(in which case the value is the same as the option text) or as an object containing key/value pairs (in which case the key/value pair maps to value value/label pairs). -
text
andtextarea
can specifyplaceholder
. -
raw
can definecontent
method, returning HTML string, element or documentFragment.
options
// element to which to append the panel
container: document.body,
// a title to add to the top of the panel
title: 'Settings',
// specifies label position relative to the input: `top` β’ `left` β’ `bottom` β’ `right`
orientation: 'left',
// collapse by clicking on title
collapsible: false,
// use a theme, see `theme` folder.
// available themes: typer, flat, control, dragon
theme: require('settings-panel/theme/none'),
//theme customization, can redefine theme defaults
palette: ['black', 'white'],
labelWidth: '9em',
inputHeight: '1.6em',
fontFamily: 'sans-serif',
fontSize: 13,
//additional css, aside from the themeβs one. Useful for custom styling
css: '',
//appends additional className to the panel element.
className: ''
panel.on(event, callback)
Attach callback to change
, input
or init
event.
The callback will recieve name
, data
and state
arguments:
panel.on('change', (name, value, state) => {
// name === 'my checkbox'
// value === false
// state === {'my checkbox': false, 'my range': 75, ...}
});
panel.get(name?)
Get the value of a field defined by name
. Or get full list of values, if name
is undefined.
panel.set(name, value|options)
Update specific field, with value or field options. You can also pass an object or array to update multiple fields:
panel.set({ 'my range': { min: -100, value: 200}, 'my color': '#fff' });
panel.update(options?)
Rerender panel with new options. Options may include values for the theme, like palette
, fontSize
, fontFamily
, labelWidth
, padding
etc, see specific theme file for possible options.
Spotted in the wild
See also
control-panel β original forked settings panel.
oui β sci-ish panel.
dat.gui β other oldschool settings panel.
quicksettings β an alternative versatile settings panel.
dis-gui β remake on dat.gui.