Skip to content

colejd/guify

Repository files navigation

guify

npm version

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