dis-gui

dis-gui

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

The above was created with the following JSX:

import * as dg from 'dis-gui';

...

<dg.GUI>
  <dg.Text label='Text' value='Hello world!'/>
  <dg.Number label='Number' value={65536}/>
  <dg.Number label='Range' value={512} min={-1024} max={1024} step={64}/>
  <dg.Checkbox label='Checkbox' checked={true}/>
  <dg.Select label='Select' options={['Option one', 'Option two', 'Option three']}/>
  <dg.Button label='Button'/>
  <dg.Folder label='Folder' expanded={true}>
    <dg.Text label='Text' value='Hello folder!'/>
    <dg.Number label='Number' value={2}/>
    <dg.Folder label='Subfolder' expanded={true}>
      <dg.Text label='Text' value='Hello subfolder!'/>
      <dg.Number label='Number' value={2}/>
    </dg.Folder>
  </dg.Folder>
  <dg.Color label='Color' expanded={true} red={0} green={128} blue={255}/>
  <dg.Gradient label='Gradient' expanded={true}/>
</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:

<dg.GUI>
  <dg.Text
    label='Text' value='Hello world!'
    onChange={function(value) {console.log(value)}}
  />
</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:

<dg.GUI>
  <dg.Number
    label='Horses'
    value={2}
    min={0}
    max={4}
    step={0.1}
    onFinishChange={function(value) {console.log(value)}}
  />
</dg.GUI>

The Button control fires an onClick event:

<dg.GUI>
  <dg.Button
    label='Run The Horses'
    onClick={function() {console.log('The horses are running.')}}
  />
</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:

<dg.GUI>
  <dg.Number
    label='Horses'
    value={2}
    min={0}
    max={4}
    step={0.1}
    onFinishChange={function(value) {console.log(value)}}
  />
</dg.GUI>

If you don't, it won't:

<dg.GUI>
  <dg.Number
    label='Horses'
    value={2}
    onFinishChange={function(value) {console.log(value)}}
  />
</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:

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

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

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

Styling

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

<dg.GUI style={{
  paddingX: 3,
  paddingY: 3,
  backgroundColor: '#EEE',
  lowlight: '#DDD',
  lowlighterr: '#FBB',
  highlight: '#444',
  separator: '1px solid #DDD',
  label: {
    fontColor: '#444',
    fontWeight: 'normal'
  }
}}>
  <dg.Text label='Text' value='Hello world!'/>
  <dg.Number label='Number' value={65536}/>
  <dg.Number label='Range' value={512} min={-1024} max={1024} step={64}/>
  <dg.Checkbox label='Checkbox' checked={true}/>
  <dg.Select label='Select' options={['Option one', 'Option two', 'Option three']}/>
  <dg.Button label='Button'/>
  <dg.Folder label='Folder' expanded={true}>
    <dg.Text label='Text' value='Hello folder!'/>
    <dg.Number label='Number' value={2}/>
    <dg.Folder label='Subfolder' expanded={true}>
      <dg.Text label='Text' value='Hello subfolder!'/>
      <dg.Number label='Number' value={2}/>
    </dg.Folder>
  </dg.Folder>
  <dg.Color label='Color' expanded={true} red={0} green={128} blue={255}/>
  <dg.Gradient label='Gradient' expanded={true}/>
</dg.GUI>

You can change the width of the labels and controls:

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

And you can position the whole thing:

<dg.GUI style={{top: '0px', right: '0px'}}>
  <dg.Gradient label='Gradient' expanded={true}/>
</dg.GUI>

<dg.GUI style={{top: '0px', left: '0px'}}>
  <dg.Color label='Color' red={255} green={128} blue={64} expanded={true}/>
</dg.GUI>

<dg.GUI style={{bottom: '0px', right: '0px'}}>
  <dg.Text label='Text' value='So many positions!'/>
</dg.GUI>

<dg.GUI style={{bottom: '0px', left: '0px'}}>
  <dg.Number label='Number'/>
</dg.GUI>

Colors

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

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

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

{
  red: 64,
  green: 128,
  blue: 255
}

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

<dg.GUI>
  <dg.Color label='Some blue color' red={64} green={128} blue={255} expanded={true}/>
</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.

<dg.GUI>
  <dg.Gradient
    label='The floor is lava!'
    stops={[
      {red: 255, green: 0, blue: 0, stop: 0},
      {red: 255, green: 255, blue: 0, stop: 0.5},
      {red: 255, green: 255, blue: 255, stop: 1.0},
    ]}
  />
</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:

<dg.GUI>
  <dg.Gradient
    label='The floor is lava!'
    stops={[
      {red: 255, green: 0, blue: 0, stop: 0},
      {red: 255, green: 255, blue: 0, stop: 0.5},
      {red: 255, green: 255, blue: 255, stop: 1.0},
    ]}
    expanded={true}
  />
</dg.GUI>

Roadmap

• Add documentation about extending dis-gui.