lil-gui

Container and Width

By default, the GUI is attached to document.body at the top right. You can specify a different container or a custom width in the constructor.

const gui = new GUI( { container: $( '#gui' ), width: 400 } );

CSS Variables

You can customize the appearance using CSS variables on the .lil-gui class:

• --width: Sets the panel width.
• --name-width: Sets the width of the controller names.
• --background-color: Sets the background.
• --widget-color: Sets the widget color.
• --padding: Sets the padding.

.lil-gui { 
	--width: 400px;
	--name-width: 65%;
	--background-color: #000;
}

Touch Styles

lil-gui applies larger touch-friendly styles via @media (pointer: coarse). To disable this, use touchStyles: false in the constructor, or manually add the .force-touch-styles class to the GUI's root element.

const gui = new GUI( { container: $( '#gui' ) } );

Use gui.save() to create a JSON-compatible object containing the current values of all controllers. Use gui.load(data) to restore them.

Important Notes:

• Name Collisions: save() will throw an error if multiple controllers or folders share the same name. Use .name('unique_name') to avoid this.
• Recursion: Both methods accept a recursive boolean parameter (default true). If false, folders are ignored.
• Format: The saved object contains controllers and folders keys.

let preset = {};

const obj = {
	value1: 'original',
	value2: 1996,
	savePreset() {
		preset = gui.save();
	},
	loadPreset() {
		gui.load( preset );
	}
};

gui.add( obj, 'value1' );
gui.add( obj, 'value2' );
gui.add( obj, 'savePreset' );

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' );

// ...

Controller-specific events

• .onChange(callback): Fires every time the value changes. The new value is passed to the callback.
• .onFinishChange(callback): Fires after a controller changes and loses focus (useful for expensive operations triggered by sliders).

gui.add( params, 'foo' ).onChange( value => {
	console.log( value );
} );

Global change handlers

You can attach handlers to the root GUI or a Folder. These events bubble up. The callback receives an event object containing:

• event.object: The object that was modified.
• event.property: The name of the property (string).
• event.value: The new value.
• event.controller: The controller instance 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
} );

Use gui.addColor() to create a color picker. It supports CSS strings, RGB objects, or integer hex values.

Note on RGB Objects/Arrays: When controlling objects like { r: 0, g: 0, b: 0 } or arrays like [0, 0, 0], lil-gui modifies the components in place without replacing the object/array. By default, channels are assumed to be between 0 and 1. You can override this range by passing a third parameter to addColor().

obj = { colorObject: { r: 0.667, g: 0, b: 1 }, colorArray: [ 0.667, 0, 1 ] }

gui.addColor( obj, 'colorObject' );
gui.addColor( obj, 'colorArray' );

// With custom range (e.g. 0-255)
obj = { colorObject: { r: 170, g: 0, b: 255 } }
gui.addColor( obj, 'colorObject', 255 );

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' );