settings-panel
v1.8.17
Published
Panel of inputs for parameter setting
Downloads
333
Maintainers
Readme
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')
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: ''
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, ...}
});
Get the value of a field defined by name
. Or get full list of values, if name
is undefined.
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' });
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.