guify

guify

Demo | Docs

Guify is a runtime JS library that gives you a simple way to build a GUI for your JS projects. It pairs very well with three.js and p5.js. Consider it an opinionated take on dat.GUI.

Here are the big features:

• Bind any UI component to any variable. Guify supports arbitrary text inputs, colors, ranges, file inputs, booleans, and more.
• Guify is easy to graft onto any page and integrate with your existing JS code. Just point your components at the variables you already have:

  var someVariable = 0;
  guify.Register([{
      {
          type: 'range',
          object: this, property: 'someProperty',
          label: 'Some Property',
          min: 0, max: 20, step: 1
      },
  }])
  

• Give it that "web app" look with an optional header bar and easy toast notifications.
• Style it however you'd like. You can use one of three built-in themes, or build your own to get exactly the look you want.

---

Installation

Below are some common ways to integrate Guify with your setup.

Quick Start (Browser)

To integrate on an existing page, you can use the transpiled version in /lib, either by including it with your files or using a CDN:

<script src="https://unpkg.com/guify@0.15.1/lib/guify.min.js"></script>

This adds a guify function at the global level, which you can use to construct the GUI. For example:

<script src="https://unpkg.com/guify@0.15.1/lib/guify.min.js"></script>

<script>
    var gui = new guify({ ... })
    gui.register([ ... ])
</script>

See the Usage guide below for more details. example.html also demonstrates this pattern.

Quick Start (NPM)

First, install with NPM: npm install --save guify

Then you can import using either require or import depending on your preference:

// ES6
import guify from 'guify'

// Require
let guify = require('guify');

Then you can make a quick GUI this way:

var gui = new guify({ ... });
gui.Register([ ... ]);

See the Usage guide below for more details.

Quick Start (React)

Check out the unofficial React port.

---

Usage

Once you have Guify available to construct in your project, make a guify instance:

var gui = new guify({
    title: "Some Title",
});

The various controls in Guify are called "components". You can feed component definitions to Guify as follows:

gui.Register([
    { // A slider representing a value between 0 and 20
        type: 'range', label: 'Range',
        min: 0, max: 20, step: 1,
        onChange: (value) => {
            console.log(value);
        }
    },
    {
        type: 'button', label: 'Button',
        action: () => {
            console.log('Button clicked!');
        }
    },
    {
        type: 'checkbox', label: 'Checkbox',
        onChange: (value) => {
            console.log(value);
        }
    }
]);

You can also bind components representing a value to your JS variables instead of using an onChange() handler. For example:

var someNumber = 10;
gui.Register([
    { // A slider representing `someNumber`, constrained between 0 and 20.
        type: 'range', label: 'Range',
        min: 0, max: 20, step: 1,
        object: this, property: 'someNumber'
    },

There are many points of customization here. See the docs at /docs/api.md. A much more robust example can also be found at example.html.

Building This Package

If you want to build this package, you can run npm install and then npm run build:prod, which will create /lib/guify.min.js.

NPM commands:

• build:prod: Creates /lib/guify.min.js, the default script used by this package.
• build:dev: Creates /lib/guify.js.
• develop: Runs build:dev and serves the /example directory as a static web page.

---

Changelog

See changelog.md.

License

MIT license. See license.md for specifics.

Credit

This package is largely based on control-panel. For setting this up, I used webpack-library-starter.

Alternatives

• dat.GUI
• Control-Panel
• Oui

Changelog

0.15.1

• Fixed a bug preventing folders from being removed with Remove().
• There was an issue introduced by 0.15.0 where the guify-container covers all content and has a higher z-index than the content underneath, eating all touch/click events. To fix this, the z-index of guify-container is now unset, and the sub-elements are given the z-index that guify-container used to get (9999).