SelectButtonGroup

SelectButtonGroup is a UI widget for displaying groups of buttons with both single and multi selection support.

Learn more about the SelectButtonGroup plugin.

constructor

constructor(options?: SelectButtonGroup.Options);

The ui.SelectButtonGroup constructor accepts an Options object that encapsulates multiple parameters:

options

[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

[optional] Is the user prevented from interacting with this ui.SelectButtonGroup? Default is false.

multi

[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

[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

[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

[optional] If nothing is selected, what value should be reported by the getSelectionValue() function? Default is undefined.

width

[optional] The width of the whole widget in pixels.

buttonWidth

[optional] The width of each button in pixels. Overridden by individual options' buttonWidth property (if provided).

buttonHeight

[optional] The height of each button in pixels. Overridden by individual options' buttonHeight property (if provided).

iconWidth

[optional] The width of each icon in pixels (for options with an icon property). Overridden by individual options' iconWidth property (if provided).

iconHeight

[optional] The height of each icon in pixels (for options with an icon property). Overridden by individual options' iconHeight property (if provided).

Methods

render()

selectButtonGroup.render(): this;

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.appendChild(selectButtonGroup.el)).

getSelection()

selectButtonGroup.getSelection(): any;

Get the current selection. The selection points to an item(s) from the options array.

getSelectionValue()

selectButtonGroup.getSelectionValue(selection?: any): any;

Get the current selection value(s). If nothing is selected, noSelectionValue is returned (default is undefined).

select(index, opt)

selectButtonGroup.select(index: number, opt?: { [key: string]: any }): void;

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)

selectButtonGroup.selectByValue(value: any, opt?: { [key: string]: any }): void;

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()

selectButtonGroup.deselect(): void;

Deselect all selected items.

remove()

selectButtonGroup.remove(): this;

Remove the button group from the DOM.

on()

selectButtonGroup.on(eventName: string, callback: EventHandler, context?: any): this;

Register a callback function that will be called whenever eventName is triggered. The optional context is an object that will be the context of the handler function (the this).

disable()

selectButtonGroup.disable(): void;

Prevent to the user's interactions.

enable()

selectButtonGroup.enable(): void;

Make the button group available to the user's interactions.

isDisabled()

selectButtonGroup.isDisabled(): boolean;

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.

Types

Options

interface Options extends mvc.ViewOptions<undefined> {
    options?: Array<{
        content?: mvc.$HTMLElement,
        value?: any,
        attrs?: object,
        selected?: boolean,
        icon?: string,
        iconSelected?: string,
        buttonWidth?: number,
        buttonHeight?: number,
        iconWidth?: number,
        iconHeight?: number,
    }>;
    disabled?: boolean;
    multi?: boolean;
    selected?: number | number[];
    singleDeselect?: boolean;
    noSelectionValue?: any;
    width?: number;
    buttonWidth?: number;
    buttonHeight?: number;
    iconWidth?: number;
    iconHeight?: number;
}