dis-gui
An extensible, styleable, & React-based controller library inspired by the venerable dat-gui.
The above was created with the following JSX:
; ... <dgGUI> <dgText label='Text' value='Hello world!'/> <dgNumber label='Number' value=65536/> <dgNumber label='Range' value=512 min=-1024 max=1024 step=64/> <dgCheckbox label='Checkbox' checked=true/> <dgSelect label='Select' options='Option one' 'Option two' 'Option three'/> <dgButton label='Button'/> <dgFolder label='Folder' expanded=true> <dgText label='Text' value='Hello folder!'/> <dgNumber label='Number' value=2/> <dgFolder label='Subfolder' expanded=true> <dgText label='Text' value='Hello subfolder!'/> <dgNumber label='Number' value=2/> </dgFolder> </dgFolder> <dgColor label='Color' expanded=true red=0 green=128 blue=255/> <dgGradient label='Gradient' expanded=true/></dgGUI>
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:
<dgGUI> <dgText label='Text' value='Hello world!' onChange= {console} /></dgGUI>
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:
<dgGUI> <dgNumber label='Horses' value=2 min=0 max=4 step=01 onFinishChange= {console} /></dgGUI>
The Button control fires an onClick event:
<dgGUI> <dgButton label='Run The Horses' onClick= {console} /></dgGUI>
Numbers
If you provide a min and max prop to the Number control, you'll get a range slider and a number field:
<dgGUI> <dgNumber label='Horses' value=2 min=0 max=4 step=01 onFinishChange= {console} /></dgGUI>
If you don't, it won't:
<dgGUI> <dgNumber label='Horses' value=2 onFinishChange= {console} /></dgGUI>
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:
<dgGUI> <dgFolder label='Folder 1'> <dgFolder label='Folder 2'> <dgFolder label='Folder 3'> <dgFolder label='Folder 4'> <dgFolder label='Folder 5'> <dgText label='You' value='...made it!'></dgText> </dgFolder> </dgFolder> </dgFolder> </dgFolder> </dgFolder></dgGUI>
Pass the expanded prop a boolean to indicate if the folder should start out open or closed:
<dgGUI> <dgFolder label='Folder 1' expanded=true> <dgText label='You' value='...made it!'></dgText> </dgFolder></dgGUI>
Styling
Pass a style property to the GUI component to change its appearance:
<dgGUI style= paddingX: 3 paddingY: 3 backgroundColor: '#EEE' lowlight: '#DDD' lowlighterr: '#FBB' highlight: '#444' separator: '1px solid #DDD' label: fontColor: '#444' fontWeight: 'normal' > <dgText label='Text' value='Hello world!'/> <dgNumber label='Number' value=65536/> <dgNumber label='Range' value=512 min=-1024 max=1024 step=64/> <dgCheckbox label='Checkbox' checked=true/> <dgSelect label='Select' options='Option one' 'Option two' 'Option three'/> <dgButton label='Button'/> <dgFolder label='Folder' expanded=true> <dgText label='Text' value='Hello folder!'/> <dgNumber label='Number' value=2/> <dgFolder label='Subfolder' expanded=true> <dgText label='Text' value='Hello subfolder!'/> <dgNumber label='Number' value=2/> </dgFolder> </dgFolder> <dgColor label='Color' expanded=true red=0 green=128 blue=255/> <dgGradient label='Gradient' expanded=true/></dgGUI>
You can change the width of the labels and controls:
<dgGUI style= labelWidth: 100 controlWidth: 400 > <dgGradient label='Gradient' expanded=true/></dgGUI>
And you can position the whole thing:
<dgGUI style=top: '0px' right: '0px'> <dgGradient label='Gradient' expanded=true/></dgGUI> <dgGUI style=top: '0px' left: '0px'> <dgColor label='Color' red=255 green=128 blue=64 expanded=true/></dgGUI> <dgGUI style=bottom: '0px' right: '0px'> <dgText label='Text' value='So many positions!'/></dgGUI> <dgGUI style=bottom: '0px' left: '0px'> <dgNumber label='Number'/></dgGUI>
Colors
Color controls take red, green, and blue props as numbers from zero to 255:
<dgGUI> <dgColor label='Some blue color' red=64 green=128 blue=255/></dgGUI>
...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:
<dgGUI> <dgColor label='Some blue color' red=64 green=128 blue=255 expanded=true/></dgGUI>
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.
<dgGUI> <dgGradient label='The floor is lava!' stops= red: 255 green: 0 blue: 0 stop: 0 red: 255 green: 255 blue: 0 stop: 05 red: 255 green: 255 blue: 255 stop: 10 /></dgGUI>
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:
<dgGUI> <dgGradient label='The floor is lava!' stops= red: 255 green: 0 blue: 0 stop: 0 red: 255 green: 255 blue: 0 stop: 05 red: 255 green: 255 blue: 255 stop: 10 expanded=true /></dgGUI>
Roadmap
- Add documentation about extending
dis-gui
.