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

Custom Controller Guides

In Use / Hot Swaps

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

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.

CSS class names are also different:

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:

Removed

API

GUI (Class)

Controller (Class)

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

src/GUI.js:49

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

Returns: Controller

src/GUI.js:201

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

Returns: Controller

src/GUI.js:258

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

Returns: GUI

src/GUI.js:274

gui.load( obj, recursive=true )

Recalls values that were saved with gui.save().

Parameters

Returns: this

src/GUI.js:284

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

Returns: object

src/GUI.js:336

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

Returns: this

src/GUI.js:382

gui.close()

Closes the GUI.

Returns: this

src/GUI.js:397

gui.show( show=true )

Shows the GUI after it's been hidden.

gui.show();
gui.show( false ); // hide
gui.show( gui._hidden ); // toggle

Parameters

Returns: this

src/GUI.js:410

gui.hide()

Hides the GUI.

Returns: this

src/GUI.js:424

gui.title( title )

Change the title of this GUI.

Parameters

Returns: this

src/GUI.js:473

gui.reset( recursive=true )

Resets all controllers to their initial values.

Parameters

Returns: this

src/GUI.js:488

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

Returns: this

src/GUI.js:506

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

Returns: this

src/GUI.js:544

gui.destroy()

Destroys all DOM elements and event listeners associated with this GUI

src/GUI.js:573

gui.controllersRecursive()

Returns an array of controllers contained by this GUI and its descendents.

Returns: Controller[]

src/GUI.js:592

gui.foldersRecursive()

Returns an array of folders contained by this GUI and its descendents.

Returns: GUI[]

src/GUI.js:604

gui.children : Array<GUI|Controller>

The list of controllers and folders contained by this GUI.

src/GUI.js:75

gui.controllers : Controller[]

The list of controllers contained by this GUI.

src/GUI.js:81

gui.domElement : HTMLElement

The outermost container element.

src/GUI.js:105

gui.folders : GUI[]

The list of folders contained by this GUI.

src/GUI.js:87

gui.parent : GUI

The GUI containing this folder, or undefined if this is the root GUI.

src/GUI.js:63

gui.root : GUI

The top level GUI containing this folder, or this if this is the root GUI.

src/GUI.js:69

gui.$children : HTMLElement

The DOM element that contains children.

src/GUI.js:133

gui.$title : HTMLElement

The DOM element that contains the title.

src/GUI.js:112

gui._closed : boolean

Used to determine if the GUI is closed. Use gui.open() or gui.close() to change this.

src/GUI.js:93

gui._hidden : boolean

Used to determine if the GUI is hidden. Use gui.show() or gui.hide() to change this.

src/GUI.js:99

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.

src/GUI.js:512

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.

src/GUI.js:550

gui._title : string

Current title of the GUI. Use gui.title( 'Title' ) to modify this value.

src/GUI.js:478

Controller (Class)

controller.name( name )

Sets the name of the controller and its label in the GUI.

Parameters

Returns: this

src/Controller.js:91

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

Returns: this

src/Controller.js:115

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

Returns: this

src/Controller.js:153

controller.reset()

Sets the controller back to its initial value.

Returns: this

src/Controller.js:187

controller.enable( enabled=true )

Enables this controller.

controller.enable();
controller.enable( false ); // disable
controller.enable( controller._disabled ); // toggle

Parameters

Returns: this

src/Controller.js:202

controller.disable( disabled=true )

Disables this controller.

controller.disable();
controller.disable( false ); // enable
controller.disable( !controller._disabled ); // toggle

Parameters

Returns: this

src/Controller.js:215

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

Returns: Controller

src/Controller.js:255

controller.min( min )

Sets the minimum value. Only works on number controllers.

Parameters

Returns: this

src/Controller.js:268

controller.max( max )

Sets the maximum value. Only works on number controllers.

Parameters

Returns: this

src/Controller.js:278

controller.step( step )

Sets the step. Only works on number controllers.

Parameters

Returns: this

src/Controller.js:288

controller.listen( listen=true )

Calls updateDisplay() every animation frame. Pass false to stop listening.

Parameters

Returns: this

src/Controller.js:297

controller.getValue()

Returns object[ property ].

Returns: any

src/Controller.js:341

controller.setValue( value )

Sets the value of object[ property ], invokes any onChange handlers and updates the display.

Parameters

Returns: this

src/Controller.js:350

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

src/Controller.js:362

controller.destroy()

Destroys this controller and removes it from the parent GUI.

src/Controller.js:379

controller.domElement : HTMLElement

The outermost container DOM element for this controller.

src/Controller.js:45

controller.initialValue : any

The value of object[ property ] when the controller was created.

src/Controller.js:39

controller.object : object

The object this controller will modify.

src/Controller.js:20

controller.parent : GUI

The GUI that contains this controller.

src/Controller.js:14

controller.property : string

The name of the property to control.

src/Controller.js:26

controller.$disable : HTMLElement

The DOM element that receives the disabled attribute when using disable()

src/Controller.js:70

controller.$name : HTMLElement

The DOM element that contains the controller's name.

src/Controller.js:53

controller.$widget : HTMLElement

The DOM element that contains the controller's "widget" (which differs by controller type).

src/Controller.js:63

controller._disabled : boolean

Used to determine if the controller is disabled. Use controller.disable( true|false ) to modify this value

src/Controller.js:33

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.

src/Controller.js:304

controller._name : string

The controller's name. Use controller.name( 'Name' ) to modify this value.

src/Controller.js:96

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.

src/Controller.js:121

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.

src/Controller.js:159