dat.gui

dat.gui is a lightweight controller library for JavaScript. It allows you to easily manipulate variables and fire functions on the fly.

Download the minified source [150.9kb]
Contribute on GitHub!

Basic Usage

<script type="text/javascript" src="gui.min.js"></script>
<script type="text/javascript">

window.onload = function() {

   var fizzyText = new FizzyText("dat.gui");

   var gui = new DAT.GUI();

   // Text field
   gui.add(fizzyText, "message");

   // Sliders with min + max
   gui.add(fizzyText, "maxSize").min(0.5).max(7);
   gui.add(fizzyText, "growthSpeed").min(0.01).max(1).step(0.05);
   gui.add(fizzyText, "speed", 0.1, 2, 0.05); // shorthand for min/max/step

   gui.add(fizzyText, "noiseStrength", 10, 100, 5);

   // Boolean checkbox
   gui.add(fizzyText, "displayOutline");

   // Fires a function called "explode"
   gui.add(fizzyText, "explode").name("Explode!"); // Specify a custom name.

};

</script>

dat.gui will infer the type of the property you're trying to add
(based on its initial value) and create the corresponding control.
The properties must be public, i.e. defined by this.prop = value.

Choosing from a list of values

gui.add(obj, "propertyName").options(1, 2, 3, 5, 8);

// Alternatively, you can specify custom labels using object syntax
gui.add(obj, "propertyName").options({'Small': 1, 'Medium': 2, 'Large': 3});

Listen for variable changes inside the GUI

To fire a function whenever a user changes a variable via the GUI, use the following syntax:

gui.add(obj, "propertyName").onChange(function(newValue) {
   alert("You changed me to " + newValue);
});

This can be slightly annoying for types like number or string. You may not want to fire a function while the user is sliding, or while they're typing. To fire a function when the user has finished making changes, use the following:

gui.add(obj, "propertyName").onFinishChange(function(newValue) {
   alert("You just finished changing me to " + newValue);
});

Finally, if you'd like to do a little something extra when a function is called, use the following:

gui.add(obj, "functionName").onFire(function() {
   alert("You called a function with dat.gui");
});

Listen for variable changes outside of the GUI

Let's say you have a variable that changes by itself from time to time. If you'd like the DAT.GUI to reflect those changes, use the listen() method.

gui.add(obj, "changingProperty").listen();

Advanced listening

By default, dat.gui will create an internal interval that checks for changes in the values you've marked with listen(). If you'd like to check for these changes in an interval of your own definition, use the following:

gui.autoListen = false; // disables internal interval
gui.add(obj, "changingProperty").listen();

// Make your own loop
setInterval(function() {
    gui.listen(); // updates values you've marked with listen()
}, 1000 / 60);

Alternatively, you can forego calling listen() on individual controllers, and instead choose to monitor changes in all values controlled by your gui.

gui.autoListen = false; // disables internal interval
gui.add(obj, "add");
gui.add(obj, "lotsa");
gui.add(obj, "properties");

// Make your own loop
setInterval(function() {
    gui.listenAll(); // updates ALL values managed by this gui
}, 1000 / 60);

Multiple panels and custom placement

You can instantiate multiple DAT.GUI objects and name them however you'd like.

var gui1 = new DAT.GUI();
var gui2 = new DAT.GUI();

// The name function overwrites the "Show Controls" text.
gui1.name("Utilities");
gui2.name("Camera Placement");

By default, dat.gui panels will be automatically added to the HTML document and fixed to the top of the screen. You can disable this behavior / styling and append the gui DOM element to a container of your choosing.

// Notice this belongs to the DAT.GUI class (uppercase)
// and not an instance thereof.
DAT.GUI.autoPlace = false;

var gui = new DAT.GUI();

// Do some custom styles ...
gui.domElement.style.position = "absolute";
gui.domElement.style.top = "20px";
gui.domElement.style.left = "20px";

document.getElementById("my-gui-container").appendChild( gui.domElement );

Pro tips.

dat.gui panels are resizeable. Drag the show/hide button.
Press 'H' to show/hide GUI's.