lil-gui
Makes a floating panel for controllers on the web. Works as a drop-in replacement for dat.gui in most projects. See Migrating for a list of breaking changes.
Basic Demo • Examples • Guide • API • GitHub
import GUI from 'lil-gui';
const gui = new GUI();
const myObject = {
myBoolean: true,
myFunction: function() { ... },
myString: 'lil-gui',
myNumber: 1
};
gui.add( myObject, 'myBoolean' ); // Checkbox
gui.add( myObject, 'myFunction' ); // Button
gui.add( myObject, 'myString' ); // Text Field
gui.add( myObject, 'myNumber' ); // Number Field
// Add sliders to number fields by passing min and max
gui.add( myObject, 'myNumber', 0, 1 );
gui.add( myObject, 'myNumber', 0, 100, 2 ); // snap to even numbers
// Create dropdowns by passing an array or object of named values
gui.add( myObject, 'myNumber', [ 0, 1, 2 ] );
gui.add( myObject, 'myNumber', { Label1: 0, Label2: 1, Label3: 2 } );
// Chainable methods
gui.add( myObject, 'myProperty' )
.name( 'Custom Name' )
.onChange( value => {
console.log( value );
} );
// Create color pickers for multiple color formats
const colorFormats = {
string: '#ffffff',
int: 0xffffff,
object: { r: 1, g: 1, b: 1 },
array: [ 1, 1, 1 ]
};
gui.addColor( colorFormats, 'string' );
Built Source •
Minified = 29.2kb, 8.3kb gzipped
Examples
- Basic Demo
- Kitchen Sink - Exhaustive demonstration of features and styles.
Custom Controller Guides
- Multiline Controller - Custom controller introduction. Creates a controller for a primitive data type.
- XY Controller - Creates a controller for an object-based data type.
- Styling Custom Controllers - Reference for CSS variables used by custom controllers.
In Use / Hot Swaps
- three.js/examples - lil-gui replaced dat.gui across all three.js examples in r135. Except for a few pages, this was done just by replacing the import URL.
- PixiJS Filters Demo Hot Swap - Replaces a very long dat.gui.
Hidden
Guide
lil-gui gives you an interface for changing the properties of any JavaScript object at runtime. It's intended as a drop-in replacement for dat.gui, implemented with more modern web standards and some new quality of life features.
The Migrating section lists any breaking changes between the two libraries. The changes are limited to the lesser-used portions of the API, but you should read it before moving a project to lil-gui.
If you've used dat.gui before, the beginning of this guide will be review. New features are introduced beginning in the Change Events section.
Installation
You can install lil-gui with npm for use with a bundler.
$ npm install lil-gui --save-dev
import GUI from 'lil-gui';
For quick sketches, you can import lil-gui directly from a CDN.
<script type="module">
import GUI from 'https://cdn.jsdelivr.net/npm/lil-gui@0.16/+esm';
</script>
The library is also available in UMD format under the namespace lil
.
<script src="https://cdn.jsdelivr.net/npm/lil-gui@0.16"></script>
<script>
var GUI = lil.GUI;
</script>
Adding Controllers
This code creates an input that lets you change this page's title.
const gui = new GUI();
gui.add( document, 'title' );
lil-gui will choose an appropriate controller type based on the property's value when it was added
to the GUI. Since document.title
was a string, a text field was created.
Here are some more of the variable types you can control:
obj = {
myBoolean: true,
myString: 'lil-gui',
myNumber: 1,
myFunction: function() { alert( 'hi' ) }
}
gui.add( obj, 'myBoolean' ); // checkbox
gui.add( obj, 'myString' ); // text field
gui.add( obj, 'myNumber' ); // number field
gui.add( obj, 'myFunction' ); // button
Numbers and Sliders
Numbers can be constrained to a range using min()
and max()
. You can use step()
to round values to multiples of a given number.
obj = { hasMin: 1, hasMax: 99, hasStep: 50 }
gui.add( obj, 'hasMin' ).min( 0 );
gui.add( obj, 'hasMax' ).max( 100 );
gui.add( obj, 'hasStep' ).step( 10 );
Number controllers with a minimum and a maximum automatically become sliders. You can use an abbreviated syntax to define them both at once.
obj = { number1: 1, number2: 50 }
gui.add( obj, 'number1', 0, 1 ); // min, max
gui.add( obj, 'number2', 0, 100, 10 ); // min, max, step
Dropdowns
You can create a dropdown for any data type by providing an array of accepted values. If you pass an object, its keys will be used as labels for the options.
obj = { size: 'Medium', speed: 1 }
gui.add( obj, 'size', [ 'Small', 'Medium', 'Large' ] )
gui.add( obj, 'speed', { Slow: 0.1, Normal: 1, Fast: 5 } )
Colors
lil-gui recognizes colors in a number of formats: CSS strings, RGB objects or integer hex values to
name a few. You can use addColor()
to create a color picker for controlling these values.
obj = {
color1: '#AA00FF',
color2: '#a0f',
color3: 'rgb(170, 0, 255)',
color4: 0xaa00ff
}
gui.addColor( obj, 'color1' );
gui.addColor( obj, 'color2' );
gui.addColor( obj, 'color3' );
gui.addColor( obj, 'color4' );
lil-gui uses an rrggbb
format for display, but it honors the original data type when writing colors (numbers remain numbers, strings remain strings). However, all string-based colors are normalized to #rrggbb
format on update.
RGB Objects & Arrays
Some libraries use objects or arrays of RGB values to describe colors. These can also be controlled
by addColor()
. The color channels are assumed to be between 0 and 1, but you can also set your
own range. Color objects and arrays are never replaced—only their components are modified.
obj = {
colorObject: { r: 0.667, g: 0, b: 1 },
colorArray: [ 0.667, 0, 1 ]
}
gui.addColor( obj, 'colorObject' );
gui.addColor( obj, 'colorArray' );
RGB Channel Ranges
The channel range for RGB objects and arrays can be overriden per controller by passing a third
parameter to addColor()
. If your colors are coming out too bright, you might need to set this to 255.
obj = {
colorObject: { r: 170, g: 0, b: 255 },
colorArray: [ 170, 0, 255 ]
}
gui.addColor( obj, 'colorObject', 255 );
gui.addColor( obj, 'colorArray', 255 );
Folders
You can organize controllers in collapsible groups using addFolder()
. The method returns a new GUI
instance representing the folder. You can add controllers to the folder just like you would with any GUI.
// top level controller
gui.add( obj, 'scale', 0, 1 );
// nested controllers
const folder = gui.addFolder( 'Position' );
folder.add( obj, 'x' );
folder.add( obj, 'y' );
folder.add( obj, 'z' );
Change Events
If you want to call a function every time a controller is changed, you can pass it to the controller's
onChange
method. The new value will be passed to your function after every change (so long as it
originates from that controller and not from code elsewhere).
gui.add( params, 'foo' ).onChange( value => {
console.log( value );
} );
The onFinishChange
handler fires after a controller changes and loses focus. This comes in handy if you're using a slow function with a controller that produces continuous change events (like numbers or colors for example).
gui.add( params, 'mySlider', 0, 1 ).onFinishChange( complexFunction );
Global Change Handlers
GUI also provides an onChange
handler that fires after changes to any of its children.
These handlers receive an event object with details about the controller that was modified.
gui.onChange( event => {
event.object // object that was modified
event.property // string, name of property
event.value // new value of controller
event.controller // controller that was modified
} );
GUI.onChange
events bubble upward. A handler applied to the root GUI will fire after every change.
Handlers applied to folders will only be called after changes to that folder or its descendents.
GUI.onFinishChange
works just like GUI.onChange
, but it only fires at the end of change events.
Listening and Updating
If a value controlled by the GUI is changed in code anywhere outside of the GUI, the new value won't
be reflected by the controller's display. You can call listen()
to update the controller's display
every frame.
gui.add( params, 'feedback', -1, 1 )
.listen()
.disable();
animate() {
params.feedback = Math.sin( Date.now() / 1000 );
}
You can also call controller.updateDisplay()
at any time to manage this behavior yourself.
Saving
Using gui.save()
you can create an object that saves the current value of all properties
added to the GUI. You can pass that object to gui.load()
to restore the saved values.
The following creates a GUI that can save a preset. Press the savePreset button, then modify any controller. Pressing the loadPreset button restores the values you saved.
let preset = {};
const obj = {
value1: 'original',
value2: 1996,
savePreset() {
// save current values to an object
preset = gui.save();
loadButton.enable();
},
loadPreset() {
gui.load( preset );
}
}
gui.add( obj, 'value1' );
gui.add( obj, 'value2' );
gui.add( obj, 'savePreset' );
const loadButton =
gui.add( obj, 'loadPreset' )
.disable();
Save Object Format
The following is an example of an object returned by gui.save()
. The object will be JSON compatible.
It can be saved to disk, unless you're using non-primitive data types in a dropdown (color objects
and arrays are fine).
{
controllers: {
value1: 'original',
value2: 1996,
},
folders: {
// if GUI has folders ...
folderName1: { controllers, folders },
folderName2: { controllers, folders }
...
}
}
Both save and load accept a recursive
parameter, which is true by default. Use save( false )
and
load( data, false )
to ignore any folders within the GUI. The saved object will contain an empty
folders object.
Name Collisions
save()
will throw an error if the GUI contains more than one controller or folder with the same
name. You can avoid these collisions by renaming the controllers with name()
.
gui.add( position, 'x' ).name( 'position.x' );
gui.add( rotation, 'x' ).name( 'rotation.x' );
Styling
By default, the GUI is added to document.body
and attached to the top right of the window with
fixed positioning. You can add the GUI to a different element by passing a container
parameter to
the constructor.
const gui = new GUI( { container: $('#gui') } );
Width and Long Names
The GUI can be made wider by passing a pixel width to the constructor. This is usually done when controller names are too long to fit within the panel.
const gui = new GUI( { width: 400 } );
The library provides a few ways to manage this using CSS variables as well.
.lil-gui {
--width: 400px;
--name-width: 65%;
}
The --width
property does the same thing as the one in the constructor, but allows us to use any valid
CSS value. Adjusting --name-width
allows you to increase the size of names relative to controllers,
which might be better than enlarging the entire panel.
CSS Variables and Custom Stylesheets
lil-gui exposes a number of CSS variables that allow you to customize colors and dimensions. You can see an exhaustive list of these variables in the Kitchen Sink demo.
.lil-gui {
--background-color: #000;
--widget-color: #0af;
--padding: 2px;
}
If you want to start a new stylesheet from scratch, the default styles can be left out entirely with
the injectStyles
parameter.
new GUI( { injectStyles: false } );
Touch Styles
Controllers are larger on touch devices to make them easier to use. By default, these styles are
applied using a CSS query @media (pointer: coarse)
. You can disable this behavior with the touchStyles
parameter.
gui = new GUI( { touchStyles: false } );
gui.domElement.classList.add( 'force-touch-styles' );
You can then apply these styles at a time of your choosing by adding the .force-touch-styles
CSS class
to the GUI's root element.
Migrating
For most projects, moving from dat.gui to lil-gui should be as simple as changing the import URL. The API is designed to be as backwards-compatible as is reasonably possible, but this section aims to address any breaking changes.
API Changes
gui.__controllers
is nowgui.controllers
.gui.__folders
is nowgui.folders
and it's an array, not a map.gui.remove( controller )
is nowcontroller.destroy()
.gui.removeFolder( folder )
is nowfolder.destroy()
.- Folders are open by default.
DOM Structure
The DOM structure of the GUI has changed, so code that interacts with dat.gui's inner DOM elements is likely to break.
gui.__ul
is nowgui.$children
.gui.__closeButton
is nowgui.$title
.domElement
is stilldomElement
for both Controller and GUI.
CSS class names are also different:
.dg.ac
is now.lil-gui.autoPlace
.
Color Controller Changes
There's one major difference in the way dat.gui and lil-gui handle color controllers: channel ranges
for RGB objects and RGB arrays are assumed to be in the range of [0-255]
in dat.gui and [0-1]
in
lil-gui.
In general, this shouldn't have much of an impact, as it's common practice to use hex values
and an onChange
handler when using dat.gui with a library like three.js that expects RGB [0-1]
.
// common three.js + dat.gui color pattern
params = { color: color.getHex() };
dat_gui.addColor( params, 'color' ).onChange( v => {
color.setHex( v )
} );
Since lil-gui and three.js agree on RGB ranges, this code can be simplified:
params = { color };
lil_gui.addColor( params, 'color' );
The other differences in color handling are fairly minor:
- lil-gui always writes to
#rrggbb
format for strings, even those defined asrgb()
or#RGB
. - lil-gui uses the native HTML
input[type=color]
tag instead of a custom color picker. - lil-gui doesn't support any HSL or alpha color formats.
Removed
- "Presets" and
gui.remember()
are gone in favor ofsave/load()
, which also removes mention oflocalStorage
. - The static
GUI.toggleHide()
method and theH to hide hotkey.
API
GUI (Class)
new GUI( { autoPlace, container, width, title, injectStyles, touchStyles, parent } )
Creates a panel that holds controllers.
new GUI();
new GUI( { container: document.getElementById( 'custom' ) } );
Parameters
-
autoPlace - Adds the GUI to
document.body
and fixes it to the top right of the page.
Default:true
-
container - Adds the GUI to this DOM element. Overrides
autoPlace
.
Optional:HTMLElement
-
width - Width of the GUI in pixels, usually set when name labels become too long. Note that you can make name labels wider in CSS with
.lil‑gui { ‑‑name‑width: 55% }
Default:245
-
title - Name to display in the title bar.
Default:Controls
-
injectStyles - Injects the default stylesheet into the page if this is the first GUI. Pass
false
to use your own stylesheet.
Default:true
-
touchStyles - Makes controllers larger on touch devices. Pass
false
to disable touch styles.
Default:true
-
parent - Adds this GUI as a child in another GUI. Usually this is done for you by
addFolder()
.
Optional:GUI
gui.add( object, property, [$1], [max], [step] )
Adds a controller to the GUI, inferring controller type using the typeof
operator.
gui.add( object, 'property' );
gui.add( object, 'number', 0, 100, 1 );
gui.add( object, 'options', [ 1, 2, 3 ] );
Parameters
-
object - The object the controller will modify.
Required:object
-
property - Name of the property to control.
Required:string
-
$1 - Minimum value for number controllers, or the set of selectable values for a dropdown.
Optional:number
orobject
orArray
-
max - Maximum value for number controllers.
Optional:number
-
step - Step value for number controllers.
Optional:number
Returns: Controller
gui.addColor( object, property, rgbScale=1 )
Adds a color controller to the GUI.
params = {
cssColor: '#ff00ff',
rgbColor: { r: 0, g: 0.2, b: 0.4 },
customRange: [ 0, 127, 255 ],
};
gui.addColor( params, 'cssColor' );
gui.addColor( params, 'rgbColor' );
gui.addColor( params, 'customRange', 255 );
Parameters
-
object - The object the controller will modify.
Required:object
-
property - Name of the property to control.
Required:string
-
rgbScale - Maximum value for a color channel when using an RGB color. You may need to set this to 255 if your colors are too dark.
Default:1
Returns: Controller
gui.addFolder( title )
Adds a folder to the GUI, which is just another GUI. This method returns the nested GUI so you can add controllers to it.
const folder = gui.addFolder( 'Position' );
folder.add( position, 'x' );
folder.add( position, 'y' );
folder.add( position, 'z' );
Parameters
- title - Name to display in the folder's title bar.
Required:string
Returns: GUI
gui.load( obj, recursive=true )
Recalls values that were saved with gui.save()
.
Parameters
-
obj
Required:object
-
recursive - Pass false to exclude folders descending from this GUI.
Default:true
Returns: this
gui.save( recursive=true )
Returns an object mapping controller names to values. The object can be passed to gui.load()
to
recall these values.
{
controllers: {
prop1: 1,
prop2: 'value',
...
},
folders: {
folderName1: { controllers, folders },
folderName2: { controllers, folders }
...
}
}
Parameters
- recursive - Pass false to exclude folders descending from this GUI.
Default:true
Returns: object
gui.open( open=true )
Opens a GUI or folder. GUI and folders are open by default.
gui.open(); // open
gui.open( false ); // close
gui.open( gui._closed ); // toggle
Parameters
- open - Pass false to close
Default:true
Returns: this
gui.close()
Closes the GUI.
Returns: this
gui.show( show=true )
Shows the GUI after it's been hidden.
gui.show();
gui.show( false ); // hide
gui.show( gui._hidden ); // toggle
Parameters
- show
Default:true
Returns: this
gui.hide()
Hides the GUI.
Returns: this
gui.title( title )
Change the title of this GUI.
Parameters
- title
Required:string
Returns: this
gui.reset( recursive=true )
Resets all controllers to their initial values.
Parameters
- recursive - Pass false to exclude folders descending from this GUI.
Default:true
Returns: this
gui.onChange( callback )
Pass a function to be called whenever a controller in this GUI changes.
gui.onChange( event => {
event.object // object that was modified
event.property // string, name of property
event.value // new value of controller
event.controller // controller that was modified
} );
Parameters
- callback
Required:function
Returns: this
gui.onFinishChange( callback )
Pass a function to be called whenever a controller in this GUI has finished changing.
gui.onFinishChange( event => {
event.object // object that was modified
event.property // string, name of property
event.value // new value of controller
event.controller // controller that was modified
} );
Parameters
- callback
Required:function
Returns: this
gui.destroy()
Destroys all DOM elements and event listeners associated with this GUI
gui.controllersRecursive()
Returns an array of controllers contained by this GUI and its descendents.
Returns: Controller[]
gui.foldersRecursive()
Returns an array of folders contained by this GUI and its descendents.
Returns: GUI[]
gui.children : Array<GUI|Controller>
The list of controllers and folders contained by this GUI.
gui.controllers : Controller[]
The list of controllers contained by this GUI.
gui.domElement : HTMLElement
The outermost container element.
gui.folders : GUI[]
The list of folders contained by this GUI.
gui.parent : GUI
The GUI containing this folder, or undefined
if this is the root GUI.
gui.root : GUI
The top level GUI containing this folder, or this
if this is the root GUI.
gui.$children : HTMLElement
The DOM element that contains children.
gui.$title : HTMLElement
The DOM element that contains the title.
gui._closed : boolean
Used to determine if the GUI is closed. Use gui.open()
or gui.close()
to change this.
gui._hidden : boolean
Used to determine if the GUI is hidden. Use gui.show()
or gui.hide()
to change this.
gui._onChange : function
Used to access the function bound to onChange
events. Don't modify this value
directly. Use the gui.onChange( callback )
method instead.
gui._onFinishChange : function
Used to access the function bound to onFinishChange
events. Don't modify this value
directly. Use the gui.onFinishChange( callback )
method instead.
gui._title : string
Current title of the GUI. Use gui.title( 'Title' )
to modify this value.
Controller (Class)
controller.name( name )
Sets the name of the controller and its label in the GUI.
Parameters
- name
Required:string
Returns: this
controller.onChange( callback )
Pass a function to be called whenever the value is modified by this controller.
The function receives the new value as its first parameter. The value of this
will be the
controller.
const controller = gui.add( object, 'property' );
controller.onChange( function( v ) {
console.log( 'The value is now ' + v );
console.assert( this === controller );
} );
Parameters
- callback
Required:function
Returns: this
controller.onFinishChange( callback )
Pass a function to be called after this controller has been modified and loses focus.
const controller = gui.add( object, 'property' );
controller.onFinishChange( function( v ) {
console.log( 'Changes complete: ' + v );
console.assert( this === controller );
} );
Parameters
- callback
Required:function
Returns: this
controller.reset()
Sets the controller back to its initial value.
Returns: this
controller.enable( enabled=true )
Enables this controller.
controller.enable();
controller.enable( false ); // disable
controller.enable( controller._disabled ); // toggle
Parameters
- enabled
Default:true
Returns: this
controller.disable( disabled=true )
Disables this controller.
controller.disable();
controller.disable( false ); // enable
controller.disable( !controller._disabled ); // toggle
Parameters
- disabled
Default:true
Returns: this
controller.options( options )
Destroys this controller and replaces it with a new option controller. Provided as a more
descriptive syntax for gui.add
, but primarily for compatibility with dat.gui.
Use caution, as this method will destroy old references to this controller. It will also change controller order if called out of sequence, moving the option controller to the end of the GUI.
// safe usage
gui.add( object1, 'property' ).options( [ 'a', 'b', 'c' ] );
gui.add( object2, 'property' );
// danger
const c = gui.add( object1, 'property' );
gui.add( object2, 'property' );
c.options( [ 'a', 'b', 'c' ] );
// controller is now at the end of the GUI even though it was added first
assert( c.parent.children.indexOf( c ) === -1 )
// c references a controller that no longer exists
Parameters
- options
Required:object
orArray
Returns: Controller
controller.min( min )
Sets the minimum value. Only works on number controllers.
Parameters
- min
Required:number
Returns: this
controller.max( max )
Sets the maximum value. Only works on number controllers.
Parameters
- max
Required:number
Returns: this
controller.step( step )
Sets the step. Only works on number controllers.
Parameters
- step
Required:number
Returns: this
controller.listen( listen=true )
Calls updateDisplay()
every animation frame. Pass false
to stop listening.
Parameters
- listen
Default:true
Returns: this
controller.getValue()
Returns object[ property ]
.
Returns: any
controller.setValue( value )
Sets the value of object[ property ]
, invokes any onChange
handlers and updates the display.
Parameters
- value
Required:any
Returns: this
controller.updateDisplay()
Updates the display to keep it in sync with the current value. Useful for updating your controllers when their values have been modified outside of the GUI.
Returns: this
controller.destroy()
Destroys this controller and removes it from the parent GUI.
controller.domElement : HTMLElement
The outermost container DOM element for this controller.
controller.initialValue : any
The value of object[ property ]
when the controller was created.
controller.object : object
The object this controller will modify.
controller.parent : GUI
The GUI that contains this controller.
controller.property : string
The name of the property to control.
controller.$disable : HTMLElement
The DOM element that receives the disabled attribute when using disable()
controller.$name : HTMLElement
The DOM element that contains the controller's name.
controller.$widget : HTMLElement
The DOM element that contains the controller's "widget" (which differs by controller type).
controller._disabled : boolean
Used to determine if the controller is disabled.
Use controller.disable( true|false )
to modify this value
controller._listening : boolean
Used to determine if the controller is currently listening. Don't modify this value
directly. Use the controller.listen( true|false )
method instead.
controller._name : string
The controller's name. Use controller.name( 'Name' )
to modify this value.
controller._onChange : function
Used to access the function bound to onChange
events. Don't modify this value directly.
Use the controller.onChange( callback )
method instead.
controller._onFinishChange : function
Used to access the function bound to onFinishChange
events. Don't modify this value
directly. Use the controller.onFinishChange( callback )
method instead.