Toolbar

The plugin to implement an interactive toolbar component is called Toolbar.

With the Toolbar plugin you can easily enrich your application with various tools. Either use built-in controls to manage other JointJS+ plugins (e.g zoomIn/zoomOut for PaperScroller, undo/redo for CommandManager) or custom tools of your desire - just choose a type of UI primitive (range, inputText, button etc.) and attach an action listener. Toolbar is a container for these tools (called "Widgets" in JointJS+).

Installation

Import the Toolbar from the ui namespace and create a new instance of it. Pass tools definitions to it to specify which Widgets should be added to the Toolbar.

import { ui } from '@joint/plus';

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'checkbox' },
        { type: 'range', name: 'slider', min: 0, max: 10, step: 1 },
        { type: 'separator' },
        { type: 'toggle', name: 'toggle', label: ''},
        'separator',  // also possible, use defaults
        { type: 'inputText' },
        { type: 'button', name: 'ok', text: 'Ok' },
        { type: 'button', name: 'cancel', text: 'Cancel' },
        { type: 'separator' }
    ]
});

document.getElementById('toolbar-holder').appendChild(toolbar.render().el);

There is also a UMD version available

Include joint.ui.toolbar.js and joint.ui.toolbar.css to your HTML:

index.html

<link href="joint.ui.toolbar.css" rel="stylesheet" type="text/css">
<script src="joint.js"></script>
<script src="joint.ui.toolbar.js"></script>

And access the Toolbar through the joint.ui namespace:

index.js

const toolbar = new joint.ui.Toolbar({
    tools: [
        { type: 'checkbox' },
        { type: 'range', name: 'slider', min: 0, max: 10, step: 1 },
        { type: 'separator' },
        { type: 'toggle', name: 'toggle', label: ''},
        'separator',  // also possible, use defaults
        { type: 'inputText' },
        { type: 'button', name: 'ok', text: 'Ok' },
        { type: 'button', name: 'cancel', text: 'Cancel' },
        { type: 'separator' }
    ]
});

document.getElementById('toolbar-holder').appendChild(toolbar.render().el);

How does Toolbar work?

The ui.Toolbar constructor takes a tools object which specifies the Widgets to be added to the Toolbar. The next thing to do is rendering the Toolbar (toolbar.render()) and appending the Toolbar HTML element (el) to a holder, which can be any element in your HTML.

Please see the demo for reference on how to do that if you're in doubts:

Open Sandbox

Referencing other JointJS+ plugins

JointJS+ comes with several built-in Widget type definitions that enable interaction with the PaperScroller and CommandManager plugins via the Toolbar. Whenever you use such a Widget type in a Toolbar, you need to pass the Widget type's required references into the Toolbar as well.

const paperScroller = new ui.PaperScroller({
    paper: paper,
    autoResizePaper: true,
});

const commandManager = new dia.CommandManager({
    graph: graph,
});

const toolbar = new ui.Toolbar({
    autoToggle: true,
    theme: 'modern',
    // initialize tools with default settings
    tools: ['zoomIn', 'zoomOut', 'zoomToFit', 'zoomSlider', 'undo', 'redo'],
    references: {
        paperScroller: paperScroller,
        commandManager: commandManager
    }
});

Try playing around with these Widget types:

Open Sandbox

Widgets

The plugin to implement a generic tool definition for the Toolbar component is called Widget.

The Widget plugin is not intended to be used directly - instead, Widget instances are created at Toolbar creation according to the provided ui.Toolbar.options.tools definitions, for example:

tools: [
    { type: 'checkbox' },
    { type: 'range', name: 'slider', min: 0, max: 10, step: 1 },
    { type: 'separator' },
    { type: 'toggle', name: 'toggle', label: '' },
    'separator',  // also possible, use defaults
    { type: 'inputText' },
    { type: 'button', name: 'ok', text: 'Ok' },
    { type: 'button', name: 'cancel', text: 'Cancel' },
    { type: 'separator' }
]

Widget types

By default, the Toolbar uses ui.widgets as the Widget namespace - the Toolbar constructor tries to match the type of each tools item object to a key of the namespace object and use the value as a constructor. An error is thrown when a Widget type cannot be found.

It is possible to specify your own Widget namespace via the ui.Toolbar.options.widgetNamespace option. This is useful if you need to add a custom Widget definition to the default namespace, for example.

The Widget types available in the ui.widgets namespace are listed below in order of their type identifier:

button

Insert a button-type input field to the Toolbar. See the API reference for ui.widgets.button for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'button', text: 'text' }
    ]
});

Open Sandbox

checkbox

Insert a checkbox-type input field to the Toolbar. See the API reference for ui.widgets.checkbox for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'checkbox', label: 'label', value: true }
    ]
});

Open Sandbox

colorPicker

Insert a color-type input field to the Toolbar. See the API reference for ui.widgets.colorPicker for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'colorPicker', value: '#4666E5' }
    ]
});

Open Sandbox

fullscreen

Insert a fullscreen button into the Toolbar, which can trigger the browser's full-screen mode for a specific HTML Element. It is implemented as a button-type input field. See the API reference for ui.widgets.fullscreen for more information.

info

The fullscreen feature is available only if the target is not displayed within an iframe. Otherwise, the button is hidden.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'fullscreen' }
    ]
});

Open Sandbox

inputNumber

Insert a number-type input field into the Toolbar. See the API reference for ui.widgets.inputNumber for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'inputNumber', label: 'label', value: 123 }
    ]
});

Open Sandbox

inputText

Insert a text-type input field into the Toolbar. See the API reference for ui.widgets.inputText for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'inputText', label: 'label', value: 'value' }
    ]
});

Open Sandbox

label

Insert a piece of text into the Toolbar. See the API reference for ui.widgets.label for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'label', text: 'text' }
    ]
});

Open Sandbox

range

Insert a range-type input field into the Toolbar. See the API reference for ui.widgets.range for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'range', min: 0, max: 100, value: 50 }
    ]
});

Open Sandbox

redo

Insert a redo button into the Toolbar, which can communicate with a CommandManager instance to redo next change in the diagram. It is implemented as a button-type input field. See the API reference for ui.widgets.redo for more information.

info

The Widget type requires the following ui.Toolbar.options.references:

• commandManager, a CommandManager instance which keeps track of the history of the diagram.

Usually used together with the undo Widget type:

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'undo' },
        { type: 'redo' }
    ],
    references: {
        commandManager: commandManager
    }
});

Open Sandbox

selectBox

Insert an instance of SelectBox into the Toolbar. See the API reference for ui.widgets.selectBox for more information.

const toolbar = new ui.Toolbar({
    tools: [
        {
            type: 'select-box', width: 200,
            options: [
                { content: 'Arial' },
                { content: 'Helvetica' },
                { content: 'Times New Roman' },
                { content: 'Courier New' }
            ]
        }
    ]
});

Open Sandbox

selectButtonGroup

Insert an instance of SelectButtonGroup into the Toolbar. See the API reference for ui.widgets.selectButtonGroup for more information.

const toolbar = new ui.Toolbar({
    tools: [
        {
            type: 'select-button-group', multi: true, selected: [1, 3],
            options: [
                { value: 'line-through', content: '<span style="text-decoration: line-through">S</span>' },
                { value: 'underline', content: '<span style="text-decoration: underline">U</span>' },
                { value: 'italic', content: '<span style="font-style: italic">I</span>' },
                { value: 'bold', content: '<span style="font-weight: bold">B</span>' }
            ]
        }
    ]
});

Open Sandbox

separator

Insert a vertical line into the Toolbar. See the API reference for ui.widgets.separator for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'label', text: 'separator -->' },
        { type: 'separator' },
        { type: 'label', text: '<-- separator'},
        { type: 'label', text: '///'},
        { type: 'label', text: 'separator (width: 20px) -->' },
        { type: 'separator', width: 20 },
        { type: 'label', text: '<-- separator (width: 20px)' },
    ]
});

Open Sandbox

textarea

Insert a textarea element into the Toolbar. See the API reference for ui.widgets.textarea for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'textarea', label: 'label', value: 'value' }
    ]
});

Open Sandbox

toggle

Insert a toggle into the Toolbar. It is implemented as a checkbox-type input field. See the API reference for ui.widgets.toggle for more information.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'toggle', label: 'label ', value: true }
    ]
});

Open Sandbox

undo

Insert an undo button into the Toolbar, which can communicate with a CommandManager instance to undo previous change in the diagram. It is implemented as a button-type input field. See the API reference for ui.widgets.undo for more information.

info

The Widget type requires the following ui.Toolbar.options.references:

• commandManager, a CommandManager instance which keeps track of the history of the diagram.

Usually used together with the redo Widget type:

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'undo' },
        { type: 'redo' }
    ],
    references: {
        commandManager: commandManager
    }
});

Open Sandbox

zoomIn

Insert a zoom-in button into the Toolbar, which can communicate with a PaperScroller instance to trigger zoom. It is implemented as a button-type input field. See the API reference for ui.widgets.zoomIn for more information.

"Zooming in" means increasing the zoom level (i.e. zoom level 2 has elements twice as large as default zoom level 1).

info

The Widget type requires the following ui.Toolbar.options.references:

• paperScroller, a PaperScroller instance whose zoom level will be changed.

Usually used together with the zoomOut ("-") and zoomToFit ("fit") Widget types:

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'zoomIn' },
        { type: 'zoomOut' },
        { type: 'zoomToFit' }
    ],
    references: {
        paperScroller: paperScroller
    }
});

Open Sandbox

zoomOut

Insert a zoom-out button into the Toolbar, which can communicate with a PaperScroller instance to trigger zoom. It is implemented as a button-type input field. See the API reference for ui.widgets.zoomOut for more information.

"Zooming out" means decreasing the zoom level (i.e. zoom level 0.5 has elements half as small as default zoom level 1).

info

The Widget type requires the following ui.Toolbar.options.references:

• paperScroller, a PaperScroller instance whose zoom level will be changed.

Usually used together with the zoomIn ("+") and zoomToFit ("fit") Widget types:

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'zoomIn' },
        { type: 'zoomOut' },
        { type: 'zoomToFit' }
    ],
    references: {
        paperScroller: paperScroller
    }
});

Open Sandbox

zoomSlider

Insert a zoom slider into the Toolbar, which can communicate with a PaperScroller instance to trigger zoom. It is implemented as a range-type input field. See the API reference for ui.widgets.zoomSlider for more information.

info

The Widget type requires the following ui.Toolbar.options.references:

• paperScroller, a PaperScroller instance whose zoom level will be changed.

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'zoomSlider' }
    ],
    references: {
        paperScroller: paperScroller
    }
});

Open Sandbox

zoomToFit

Insert a zoom-to-fit button into the Toolbar, which can communicate with a PaperScroller instance to trigger zoom. It is implemented as a button-type input field. See the API reference for ui.widgets.zoomToFit for more information.

"Zooming to fit" means changing the zoom level such that all of the diagram content (Elements and Links) are completely visible in the viewport.

info

The Widget type requires the following ui.Toolbar.options.references:

• paperScroller, a PaperScroller instance whose zoom level will be changed.

Usually used together with the zoomIn ("+") and zoomOut ("-") Widget types:

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'zoomIn' },
        { type: 'zoomOut' },
        { type: 'zoomToFit' }
    ],
    references: {
        paperScroller: paperScroller
    }
});

Open Sandbox

Events

The Toolbar acts as a proxy for Widget events, so an event triggered on a Widget instance can also be caught on the Toolbar instance. Event names are prefixed with the Widget instance's name followed by a colon : to make it possible to distinguish which Toolbar Widget the event is coming from.

See the API reference for ui.widgets for a list of events which may be triggered by each Widget type.

info

In order to be able to listen to a Widget instance, the Toolbar Widget in question must be created with a name property set.

Example usage:

const toolbar = new ui.Toolbar({
    tools: [
        { type: 'toggle', name: 'toggle' },
        { type: 'button', name: 'ok', text: 'Ok' },
        { type: 'button', name: 'cancel', text: 'Cancel' },
    ]
});

toolbar.on('toggle:change', function(value, event) {
    console.log(value, event);
});

toolbar.on('ok:pointerclick', function(event) {
    console.log('ok clicked');
});

toolbar.on('cancel:pointerclick', function(event) {
    console.log('cancel clicked');
});

document.getElementById('toolbar-holder').appendChild(toolbar.render().el);