dis-gui

An extensible, styleable, & React-based controller library inspired by the venerable dat-gui.

The above was created with the following JSX:

1import * as dg from 'dis-gui';
2
3...
4
5<dg.GUI>
6  <dg.Text label='Text' value='Hello world!'/>
7  <dg.Number label='Number' value={65536}/>
8  <dg.Number label='Range' value={512} min={-1024} max={1024} step={64}/>
9  <dg.Checkbox label='Checkbox' checked={true}/>
10  <dg.Select label='Select' options={['Option one', 'Option two', 'Option three']}/>
11  <dg.Button label='Button'/>
12  <dg.Folder label='Folder' expanded={true}>
13    <dg.Text label='Text' value='Hello folder!'/>
14    <dg.Number label='Number' value={2}/>
15    <dg.Folder label='Subfolder' expanded={true}>
16      <dg.Text label='Text' value='Hello subfolder!'/>
17      <dg.Number label='Number' value={2}/>
18    </dg.Folder>
19  </dg.Folder>
20  <dg.Color label='Color' expanded={true} red={0} green={128} blue={255}/>
21  <dg.Gradient label='Gradient' expanded={true}/>
22</dg.GUI>

Demo

Try out the live demo.

Installation

npm install dis-gui

Note: dis-gui has peer dependencies react@^15.3.0 react-addons-update@^15.3.1 react-dom@^15.3.0

Events

The onChange event is fired when a control's value changes:

1<dg.GUI>
2  <dg.Text
3    label='Text' value='Hello world!'
4    onChange={function(value) {console.log(value)}}
5  />
6</dg.GUI>

The onFinishChange event fires when the user performs some action that indicates that they are finished changing a value, like hitting enter or tabbing out of a text or number field, or releasing a mouse button after dragging a number range thumb:

1<dg.GUI>
2  <dg.Number
3    label='Horses'
4    value={2}
5    min={0}
6    max={4}
7    step={0.1}
8    onFinishChange={function(value) {console.log(value)}}
9  />
10</dg.GUI>

The Button control fires an onClick event:

1<dg.GUI>
2  <dg.Button
3    label='Run The Horses'
4    onClick={function() {console.log('The horses are running.')}}
5  />
6</dg.GUI>

Numbers

If you provide a min and max prop to the Number control, you'll get a range slider and a number field:

1<dg.GUI>
2  <dg.Number
3    label='Horses'
4    value={2}
5    min={0}
6    max={4}
7    step={0.1}
8    onFinishChange={function(value) {console.log(value)}}
9  />
10</dg.GUI>

If you don't, it won't:

1<dg.GUI>
2  <dg.Number
3    label='Horses'
4    value={2}
5    onFinishChange={function(value) {console.log(value)}}
6  />
7</dg.GUI>

If the user enters a value that is not a number, the onChange and onFinishChange event will not fire, and the value will be highlighted with the value defined by lowlighterr in the style property of the GUI component:

Folders

Nest controls to arbitrary depth with the Folder component:

1<dg.GUI>
2  <dg.Folder label='Folder 1'>
3    <dg.Folder label='Folder 2'>
4      <dg.Folder label='Folder 3'>
5        <dg.Folder label='Folder 4'>
6          <dg.Folder label='Folder 5'>
7            <dg.Text label='You' value='...made it!'></dg.Text>
8          </dg.Folder>
9        </dg.Folder>
10      </dg.Folder>
11    </dg.Folder>
12  </dg.Folder>
13</dg.GUI>

Pass the expanded prop a boolean to indicate if the folder should start out open or closed:

1<dg.GUI>
2  <dg.Folder label='Folder 1' expanded={true}>
3    <dg.Text label='You' value='...made it!'></dg.Text>
4  </dg.Folder>
5</dg.GUI>

Styling

Pass a style property to the GUI component to change its appearance:

1<dg.GUI style={{
2  paddingX: 3,
3  paddingY: 3,
4  backgroundColor: '#EEE',
5  lowlight: '#DDD',
6  lowlighterr: '#FBB',
7  highlight: '#444',
8  separator: '1px solid #DDD',
9  label: {
10    fontColor: '#444',
11    fontWeight: 'normal'
12  }
13}}>
14  <dg.Text label='Text' value='Hello world!'/>
15  <dg.Number label='Number' value={65536}/>
16  <dg.Number label='Range' value={512} min={-1024} max={1024} step={64}/>
17  <dg.Checkbox label='Checkbox' checked={true}/>
18  <dg.Select label='Select' options={['Option one', 'Option two', 'Option three']}/>
19  <dg.Button label='Button'/>
20  <dg.Folder label='Folder' expanded={true}>
21    <dg.Text label='Text' value='Hello folder!'/>
22    <dg.Number label='Number' value={2}/>
23    <dg.Folder label='Subfolder' expanded={true}>
24      <dg.Text label='Text' value='Hello subfolder!'/>
25      <dg.Number label='Number' value={2}/>
26    </dg.Folder>
27  </dg.Folder>
28  <dg.Color label='Color' expanded={true} red={0} green={128} blue={255}/>
29  <dg.Gradient label='Gradient' expanded={true}/>
30</dg.GUI>

You can change the width of the labels and controls:

1<dg.GUI style={{ labelWidth: 100, controlWidth: 400 }}>
2  <dg.Gradient label='Gradient' expanded={true}/>
3</dg.GUI>

And you can position the whole thing:

1<dg.GUI style={{top: '0px', right: '0px'}}>
2  <dg.Gradient label='Gradient' expanded={true}/>
3</dg.GUI>
4
5<dg.GUI style={{top: '0px', left: '0px'}}>
6  <dg.Color label='Color' red={255} green={128} blue={64} expanded={true}/>
7</dg.GUI>
8
9<dg.GUI style={{bottom: '0px', right: '0px'}}>
10  <dg.Text label='Text' value='So many positions!'/>
11</dg.GUI>
12
13<dg.GUI style={{bottom: '0px', left: '0px'}}>
14  <dg.Number label='Number'/>
15</dg.GUI>

Colors

Color controls take red, green, and blue props as numbers from zero to 255:

1<dg.GUI>
2  <dg.Color label='Some blue color' red={64} green={128} blue={255}/>
3</dg.GUI>

...and return an object like the following in their onChange and onFinishChange events:

1{
2  red: 64,
3  green: 128,
4  blue: 255
5}

Color controls can be expanded by clicking on them, or you can pass the expanded prop a boolean to expand them by default:

1<dg.GUI>
2  <dg.Color label='Some blue color' red={64} green={128} blue={255} expanded={true}/>
3</dg.GUI>

Gradients

The Gradient control takes a stops prop, which is an array of objects that have red, green, blue, and stop properties. The color properties behave identically to the Color control, and the stop property is a number from zero to one that represents the position of the stop.

1<dg.GUI>
2  <dg.Gradient
3    label='The floor is lava!'
4    stops={[
5      {red: 255, green: 0, blue: 0, stop: 0},
6      {red: 255, green: 255, blue: 0, stop: 0.5},
7      {red: 255, green: 255, blue: 255, stop: 1.0},
8    ]}
9  />
10</dg.GUI>

Like the Color control, the Gradient control will expand when the user clicks it or if you add the expanded boolean property set to true:

1<dg.GUI>
2  <dg.Gradient
3    label='The floor is lava!'
4    stops={[
5      {red: 255, green: 0, blue: 0, stop: 0},
6      {red: 255, green: 255, blue: 0, stop: 0.5},
7      {red: 255, green: 255, blue: 255, stop: 1.0},
8    ]}
9    expanded={true}
10  />
11</dg.GUI>

Roadmap

• Add documentation about extending dis-gui.