embeddable panel of inputs for parameter setting
Clone or download
Pull request Compare This branch is 20 commits ahead, 6 commits behind freeman-lab:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo
dist
images
src
.babelrc
.eslintrc
.gitignore
.npmignore
LICENSE
README.md
contributors.md
package.json
webpack.config.js
webpack.prod.js
yarn.lock

README.md

control-panel

NPM version experimental

This is a React port of control-panel that aims to replicate the functionality of the original exactly while making it easily usable from React. All of the features of the original have been brought over, and the API remains very similar.

Embeddable panel of inputs for adding parameter selection to your app or visualization. Modern and minimalist design. Fully encapsulated module including JS and CSS. Can easily be added to any app or page. Heavily inspired by dat-gui, but streamlined, simplified, and written as a npm module.

LIVE DEMO

themes


Supports the following input types

rangecheckboxtextcolorbuttonintervalselect


Includes the following themes

darklight

Want to contribute a new theme or input type? Submit a PR!

install

Add to your project with

npm install control-panel

The UI uses the Hack font which users may not have installed on their machines locally. To include a version dynamically, add the following line to your <head>:

<style type="text/css" rel="stylesheet"//cdn.jsdelivr.net/font-hack/2.019/css/hack.min.css></style>

example

Create a panel with four elements and add to your page in the top right.

import ControlPanel, {
  Button,
  Checkbox,
  Multibox,
  Select,
  Text,
  Color,
  Range,
  Interval,
} from 'react-control-panel';

const initialState = {
  'range slider': 20,
  'stepped slider': 0.6,
  interval: [25, 50],
  text: 'my setting',
  checkbox: true,
  'color rgb': 'rgb(100, 200, 100',
  'color hex': '#30b2ba',
  selection: 'option 1',
  'multiple checkboxes': [true, true],
};

const DemoPanel = () => (
  <ControlPanel
    theme="dark"
    title="Demo Panel"
    initialState={initialState}
    onChange={console.log}
    width={500}
    style={{ marginRight: 30 }}
  >
    <Range label="range slider" min={0} max={100} />
    <Range label="stepped slider" min={0} max={1} />
    <Interval label="interval" min={0} max={100} />
    <Text label="text" />
    <Checkbox label="checkbox" />
    <Color label="color rgb" format="rgb" />
    <Color label="color hex" format="hex" />
    <Button label="gimme an alert" action={() => alert('clicked')} />
    <Select label="selection" options={{ 'option 1': 1, 'option 2': 2 }} />
    <Multibox
      label="multiple checkboxes"
      colors={['rgb(100,120,230)', 'rgb(210,100,190)']}
      names={['box1', 'box2']}
    />
  </ControlPanel>
);

classic setting definitions

It's also possible to use the old array-based definition system from the original version:

<DemoPanel
  theme="dark"
  title="Array-Declared Control Panel"
  position="bottom-right"
  settings={[
    { type: 'range', label: 'my range', min: 0, max: 100, initial: 20 },
    { type: 'range', label: 'log range', min: 0.1, max: 100, initial: 20, scale: 'log' },
    { type: 'text', label: 'my text', initial: 'my cool setting' },
    { type: 'checkbox', label: 'my checkbox', initial: true },
    { type: 'color', label: 'my color', format: 'rgb', initial: 'rgb(10,200,0)' },
    {
      type: 'button',
      label: 'gimme an alert',
      action: () => {
        alert('hello!');
      },
    },
    {
      type: 'select',
      label: 'select one',
      options: ['option 1', 'option 2'],
      initial: 'option 1',
    },
    { type: 'multibox', label: 'check many', count: 3, initial: [true, false, true] },
  ]}
/>

usage

The ControlPanel component takes an array of children setting components that all receive part of the state. They each take additional props that can be used to configure their behavior. The ControlPanel itself takes a variety of props itself:

  • initialState is an object mapping label to initial value for each of the settings for the control panel. It is required, and a value should be supplied for each of the settings components.
  • onChange accepts a callback that has the following signature: (label, newValue, state) where state is the full state object for the entire panel. The supplied function will be called every time that any of the settings are updated.
  • theme can specify lightdark or provide an object (see themes.js for format)
  • title a title to add to the top of the panel
  • width width of panel in pixels
  • position where to place the panel as top-lefttop-rightbottom-leftbottom-right, if undefined will just use relative positioning
  • draggable makes the entire control panel draggable.
  • style is an object of inline styles that will be merged into the default styles of the panel's main component.
  • settings is an array of setting definitions in the same format as the orignal library; this can be used as an alternative to passing in setting components as children. See the classic setting definitions section above for an example.
  • state is an external state object that will be used to replace the state maintained by the panel itself. For more info, see the external state section below.
  • contextCb accepts a callback that will be provided with an object that can be used to get and set the inner state used by the panel directly. For more info, see the panel context section below.

Each child setting component must be one of RangeInputCheckboxColorIntervalSelect. Each label must be unique as it maps to a top-level key of the state object for the whole ControlPanel.

Some setting components have additional properties:

  • Inputs of type range can specify a min, max, and step (or integer steps). Scale can be either 'linear' (default) or 'log'. If a log scale, the sign of min, max, and initial must be the same and only steps is permitted (since the step size is not constant on a log scale).
  • Inputs of type color can specify a format as either rgbhexarray
  • Inputs of type button can specify an action callback. Button inputs are not reflected in the state and do not trigger an 'input' event.
  • Inputs of type interval obey the same semantics as range inputs, except the input and output is a two-element array corresponding to the low/high bounds, e.g. initial: [1, 7.5].
  • Inputs of type select can specify a list of options, either as an Array (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).
  • Inputs of type multibox can specify a number of checkboxes, either by providing a count or a list of names from which the number will be inferred, in which case the color of each box and a text name can also be provided as lists colors and names

external state

It is sometimes desirable to hoist the state for a panel up into something like Redux rather than letting the component handle it itself. This is supported by passing a state prop into the ControlPanel which you are in charge of keeping updated with new values provided by the panel's onChange prop callback. Here's an example of how this would work with state hoisted into a parent component:

class Wrapper extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      label1: 'val',
      ...
    };
  }

  render() {
    return (
      <ControlPanel
        state={this.state}
        {/* \/ not necessary - this is inferred automatically when `state` is provided */}
        {/*initialState={this.state}*/}
        onChange={(key, val) => this.setState({ [key]: val })}
        title='Panel with External State'
      />
        ...
    </ControlPanel>
    );
  }
}

Please note that panel context will not work if you use external state.

panel context

As mentioned above, it's possible to pass a callback to the ControlPanel component which will be supplied with a special context object after the component has mounted. This allows the underlying state to be directly viewed and manipulated from other parts of the application while still being reflected dynamically in the UI. Here's an example:

const handleContext = ctx => {
  console.log(ctx['label']); // prints the stored value for that setting
  ctx['my range'] = 10; // this sets the value of the 'my range' setting to 10 in the panel
  ctx['multibox'][1] = false; // this doesn't work; you can only set top-level setting values
  ctx['multibox'] = [true, false, true]; // do this instead
  console.log(Object.entries(ctx)); // this works, even with the polyfill
};

<ControlPanel contextCb={handleContext}>...</ControlPanel>;

In browsers that don't support the ES6 Proxy API, a shallow polyfill is used which allows values to be get, set, and listed which should be enough for most applications.

Please note that you cannot use external state if you are supplying a panel context callback.

development

To develop on this library, simply run the following commands:

  • yarn
  • yarn start

Then, open localhost:9000 in your web browser. The page being shown is found in /demo, and any changes to it or the library itself will be hot-reloaded.

see also