JointJS+ SelectButtonGroup

You may see the name Rappid in our documentation, code and other materials. Rappid has been replaced by a new brand, JointJS+. This change has no effect on functionality. To avoid confusion, please consider Rappid and JointJS+ as synonyms. Read more here.

ui.SelectButtonGroup

ui.SelectButtonGroup is a UI widget for displaying groups of buttons with both single and multi selection support. The buttons can contain arbitrary HTML.

Installation

Include joint.ui.selectButtonGroup.js and joint.ui.selectButtonGroup.css files to your HTML:

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

Usage

Create an object of ui.SelectButtonGroup type, render it with the render() method and append the generated HTML element anywhere in your DOM:

var buttonGroup = new joint.ui.SelectButtonGroup({
    multi: true,
    selected: [1, 3],
    options: [
        { value: 'line-through', content: 'S' },
        { value: 'underline', content: 'U' },
        { value: 'italic', content: 'I' },
        { value: 'bold', content: 'B' }
    ]
});
document.body.appendChild(buttonGroup.render().el);

More examples

ui.SelectButtonGroup with icons

Configuration

The following table lists options that you can pass to the ui.SelectButtonGroup constructor function:

options Object[] Optional. An array of items (the buttons). Each item is an object with the following properties:
content string Optional. The content of the item. It can be either a plain string or a string containing HTML code.
value any Optional. The value of the item. It can be a string, a number or any other JavaScript object. By default, the value is considered to be equal to the content property.
attrs Object Optional. A hierarchical object that adds styling to component HTML elements of the option. For example, the following attrs object would add a tooltip to the option:
{
  '.select-button-group-button': {
    'data-tooltip': 'My tooltip'
  }
}
selected boolean Optional. Should this item be selected by default? Default is false.
icon string Optional. A path to an image to be added to the option's button.
iconSelected string Optional. A path to an image to be added to the option's button when it is selected. By default, the selected state uses icon (if provided).
buttonWidth number Optional. The width of the button in pixels.
buttonHeight number Optional. The height of the button in pixels.
iconWidth number Optional. The width of icon in pixels (if provided).
iconHeight number Optional. The height of icon in pixels (if provided).
disabled boolean Optional. Is the user prevented from interacting with this ui.SelectButtonGroup? Default is false.
multi boolean Optional. Is this a multiple-choice set? (That is, is it allowed for multiple buttons to be selected at the same time?) Default is false.
selected number | number[] Optional. Which options should be selected by default?
If multi === false, expects a number - the index of the selected option.
If multi === true, expects an array of numbers - indices of all selected options.
By default, this property is undefined. In that case, the widget determines selected items according to individual options' selected property.
singleDeselect boolean Optional. If multi === false, is the user allowed to deselect the currently-selected icon by clicking on it? Default is false (radio-button-like behavior).
noSelectionValue any Optional. If nothing is selected, what value should be reported by the getSelectionValue() function? Default is undefined.
width number Optional. The width of the whole widget in pixels.
buttonWidth number Optional. The width of each button in pixels. Overridden by individual options' buttonWidth property (if provided).
buttonHeight number Optional. The height of each button in pixels. Overridden by individual options' buttonHeight property (if provided).
iconWidth number Optional. The width of each icon in pixels (for options with an icon property). Overridden by individual options' iconWidth property (if provided).
iconHeight number Optional. The height of each icon in pixels (for options with an icon property). Overridden by individual options' iconHeight property (if provided).

API

render() Render the button group. Note that once you render the button group, you can use the el property that points to the container HTML element and append it anywhere in the DOM (e.g. $(document.body).append(selectButtonGroup.el)).
getSelection() Get the current selection. The selection points to an item(s) from the options array.
getSelectionValue() Get the current selection value(s). If nothing is selected, noSelectionValue is returned (default is undefined).
select(index, opt) Select an item. index is the index to the options array. opt is optional and can be an arbitrary object that will be passed to the option:select event handler.
selectByValue(value) Select an item by value. The selected item will be chosen based on a strict equality of the value passed an a value (content) of any of the items.
deselect() Deselect all selected items.
remove() Remove the button group from the DOM.
on(event, handler [, context]) Register a handler function that will be called whenever event is triggered. The optional context is an object that will be the context of the handler function (the this).
disable() Prevent to the user's interactions.
enable() Make the button group available to the user's interactions.
isDisabled() Check if the button group is prevented to the user's interactions.

Events

The ui.SelectButtonGroup object triggers various events that you can react on. Events can be handled by using the on() method (see above).

option:hover Triggered when the user hovers over one of the items. The handler is passed the option object and the index of the option in the options array.
option:select Triggered when the user selects an item. The handler is passed the option object and the index of the option in the options array. If you selected the item with the select(index, opt) method, the third argument to the event handler will be your opt object.
mouseout Triggered when the user leaves the entire button group with mouse cursor. The handler is passed an event object as the only argument.