ButtonGroup — Smart UI JavaScript API

ButtonGroup — Smart UI JavaScript API

On this page + Quick start

Quick start · JavaScript

Complete starter source per framework. Run the scaffold/install command first, then replace the listed files with the full code below.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>ButtonGroup - JavaScript Quick Start</title>
  <link rel="stylesheet" href="./node_modules/smart-webcomponents/source/styles/smart.default.css" />
</head>
<body>
  <smart-button-group id="demo-buttongroup"></smart-button-group>

  <script type="module">
    import './node_modules/smart-webcomponents/source/modules/smart.buttongroup.js';

    const el = document.getElementById('demo-buttongroup');
    if (el) {

      el.dataSource = [
        { label: 'Left' },
        { label: 'Center' },
        { label: 'Right' }
      ];
      el.selectionMode = 'one';
      el.selectedIndexes = [1];

      el.addEventListener('change', (event) => console.log('change:', event.detail || event));
    }
  </script>
</body>
</html>
For AI tooling

Developer Quick Reference

Component: ButtonGroup   Framework: JavaScript   Selector: smart-button-group

API counts: 15 properties, 1 methods, 1 events

Common properties: 0, 1, 2, 3, 4, 5

Common methods: select()

Common events: change

Module hint: smart-webcomponents/source/modules/smart.buttongroup.js

ButtonGroup creates a set of buttons that can work as normal buttons, radio buttons or checkboxes.

Class

ButtonGroup

ButtonGroup

ButtonGroup creates a set of buttons that can work as normal buttons, radio buttons or checkboxes.

Selector

smart-button-group

Quick picks

changedataSourcedisabled

Properties

AanimationSets or retrieves the current animation mode for the component. When the property is set to 'none', all animations are disabled, resulting in immediate transitions without visual effects. Otherwise, specifying a different mode enables animations according to the selected option.
DdataSourceConfigures the set of buttons to be displayed. The dataSource property accepts multiple formats: it can be an array of strings or numbers—each representing a button—or an array of objects, where each object defines the properties of a button (for example, with attributes such as label for the button text and value for its underlying value). Alternatively, dataSource can be a function (callback) that returns an array in either of these formats. This flexibility allows you to define button configurations statically or generate them dynamically based on custom logic.
DdisabledSpecifies whether the element is interactive and can be used by the user. When enabled, the element responds to user input; when disabled, the element is non-interactive and usually appears visually distinct to indicate it is unavailable.
LlocaleSpecifies or retrieves the currently selected language for the component. This property works together with messages, which provides the corresponding localized texts or translations for each available language. Changing the language will update the displayed messages based on the selected locale.
LlocalizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module before they are displayed to the user. Use this to modify, translate, or enrich message content based on your application's specific requirements.
MmessagesDefines or retrieves an object containing text strings used within the widget, allowing these strings to be localized for different languages. This property works in conjunction with the locale property to provide translated text for the widget's user interface, enabling support for internationalization.
NnameSets or retrieves the value of the element's name attribute. The name attribute is used to identify form fields when submitting an HTML form, allowing the form data to be sent as key-value pairs to the server. This attribute is essential for grouping related input elements and accessing their submitted values on the server side.
RreadonlyWhen the custom element has the 'readonly' attribute set, its value cannot be modified by the user. Interaction methods such as typing, selecting, or altering content are disabled; however, users are still able to focus on and copy content from the element if desired. Any attempts to change the value—either via keyboard, mouse, or programmatic user actions—will have no effect.
RrightToLeftGets or sets a value that determines whether the element’s layout and text direction are aligned for right-to-left (RTL) locales, such as those using Arabic or Hebrew scripts. When enabled, this property ensures proper alignment and rendering for languages that read from right to left."
SselectedIndexesGets or sets the indexes of the selected buttons within the group as an array of numbers. Each number corresponds to the zero-based index of a selected button. Used to track multiple selected buttons within the group.
SselectedValuesGets or sets the selected values of the button group component as an array of strings. Each string in the array corresponds to the value attribute of a selected button within the group. This property can be used to programmatically read which buttons are currently selected or to define the initial selection state.
SselectionModeSpecifies how items within the element can be selected—for example, allowing single selection, multiple selections, or no selection at all.
TthemeSpecifies the visual theme to be applied to the element. The theme controls the overall appearance, including colors, typography, and style variations, ensuring the element is displayed consistently according to the selected design.
UunfocusableIf set to true, this property prevents the element from receiving keyboard focus, making it unreachable via keyboard navigation (such as the Tab key).
UunlockKeyDefines or retrieves the unlockKey, a unique identifier or code required to activate and gain access to the product’s full features.

Events

CchangeThe "change" event is triggered whenever the values of selectedValues or selectedIndexes are updated. This event occurs whenever the user selects or deselects an option, or when the selection state is modified programmatically. Use this event to respond to changes in the selection, such as updating the UI or performing validation.

Methods

SselectToggles the selection state of an item within the element, allowing users to either select or deselect the specified item based on its current state.

Properties

animationSets or retrieves the current animation mode for the component. When the property is set to 'none', all animations are disabled, resulting in immediate transitions without visual effects. Otherwise, specifying a different mode enables animations according to the selected option."none" | "simple" | "advanced"

Sets or retrieves the current animation mode for the component. When the property is set to 'none', all animations are disabled, resulting in immediate transitions without visual effects. Otherwise, specifying a different mode enables animations according to the selected option.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"
Try a demo showcasing the animation property.

Examples

Markup and runtime examples for animation:

HTML:

<smart-button-group animation="none"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.animation = "simple";

Read the current value:

const el = document.querySelector('smart-button-group');
const animation = el.animation;

dataSourceConfigures the set of buttons to be displayed. The dataSource property accepts multiple formats: it can be an array of strings or numbers—each representing a button—or an array of objects, where each object defines the properties of a button (for example, with attributes such as label for the button text and value for its underlying value). Alternatively, dataSource can be a function (callback) that returns an array in either of these formats. This flexibility allows you to define button configurations statically or generate them dynamically based on custom logic.any

Configures the set of buttons to be displayed. The dataSource property accepts multiple formats: it can be an array of strings or numbers—each representing a button—or an array of objects, where each object defines the properties of a button (for example, with attributes such as label for the button text and value for its underlying value). Alternatively, dataSource can be a function (callback) that returns an array in either of these formats. This flexibility allows you to define button configurations statically or generate them dynamically based on custom logic.

Default value

[]
Try a demo showcasing the dataSource property.

Examples

Markup and runtime examples for dataSource:

HTML:

<smart-button-group data-source="[{ label: "item 1", value: "1" }, { label: "item 2", value: "2" }]"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.dataSource = ["new item 1", "new item 2"];

Read the current value:

const el = document.querySelector('smart-button-group');
const dataSource = el.dataSource;

disabledSpecifies whether the element is interactive and can be used by the user. When enabled, the element responds to user input; when disabled, the element is non-interactive and usually appears visually distinct to indicate it is unavailable.boolean

Specifies whether the element is interactive and can be used by the user. When enabled, the element responds to user input; when disabled, the element is non-interactive and usually appears visually distinct to indicate it is unavailable.

Default value

false

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-button-group disabled></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.disabled = false;

Read the current value:

const el = document.querySelector('smart-button-group');
const disabled = el.disabled;

localeSpecifies or retrieves the currently selected language for the component. This property works together with messages, which provides the corresponding localized texts or translations for each available language. Changing the language will update the displayed messages based on the selected locale.string

Specifies or retrieves the currently selected language for the component. This property works together with messages, which provides the corresponding localized texts or translations for each available language. Changing the language will update the displayed messages based on the selected locale.

Default value

"en"
Try a demo showcasing the locale property.

Examples

Markup and runtime examples for locale:

HTML:

<smart-button-group locale="de"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.locale = "fr";

Read the current value:

const el = document.querySelector('smart-button-group');
const locale = el.locale;

localizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module before they are displayed to the user. Use this to modify, translate, or enrich message content based on your application's specific requirements.function | null

A callback function that allows you to customize the formatting of messages returned by the Localization Module before they are displayed to the user. Use this to modify, translate, or enrich message content based on your application's specific requirements.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

<smart-button-group localize-format-function="function(defaultMessage, message, messageArguments){return '...'}"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.localizeFormatFunction = "function(defaultMessage, message, messageArguments){return '...'}";

Read the current value:

const el = document.querySelector('smart-button-group');
const localizeFormatFunction = el.localizeFormatFunction;

messagesDefines or retrieves an object containing text strings used within the widget, allowing these strings to be localized for different languages. This property works in conjunction with the locale property to provide translated text for the widget's user interface, enabling support for internationalization.object

Defines or retrieves an object containing text strings used within the widget, allowing these strings to be localized for different languages. This property works in conjunction with the locale property to provide translated text for the widget's user interface, enabling support for internationalization.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"htmlTemplateNotSuported": "{{elementType}}: Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."

}

Examples

Markup and runtime examples for messages:

HTML:

<smart-button-group messages="{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss."}}"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}};

Read the current value:

const el = document.querySelector('smart-button-group');
const messages = el.messages;

nameSets or retrieves the value of the element's name attribute. The name attribute is used to identify form fields when submitting an HTML form, allowing the form data to be sent as key-value pairs to the server. This attribute is essential for grouping related input elements and accessing their submitted values on the server side.string

Sets or retrieves the value of the element's name attribute. The name attribute is used to identify form fields when submitting an HTML form, allowing the form data to be sent as key-value pairs to the server. This attribute is essential for grouping related input elements and accessing their submitted values on the server side.

Default value

""""

Examples

Markup and runtime examples for name:

HTML:

<smart-button-group name="Name"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.name = "New Name";

Read the current value:

const el = document.querySelector('smart-button-group');
const name = el.name;

readonlyWhen the custom element has the 'readonly' attribute set, its value cannot be modified by the user. Interaction methods such as typing, selecting, or altering content are disabled; however, users are still able to focus on and copy content from the element if desired. Any attempts to change the value—either via keyboard, mouse, or programmatic user actions—will have no effect.boolean

When the custom element has the 'readonly' attribute set, its value cannot be modified by the user. Interaction methods such as typing, selecting, or altering content are disabled; however, users are still able to focus on and copy content from the element if desired. Any attempts to change the value—either via keyboard, mouse, or programmatic user actions—will have no effect.

Default value

false
Try a demo showcasing the readonly property.

Examples

Markup and runtime examples for readonly:

HTML attribute:

<smart-button-group readonly></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.readonly = false;

Read the current value:

const el = document.querySelector('smart-button-group');
const readonly = el.readonly;

rightToLeftGets or sets a value that determines whether the element’s layout and text direction are aligned for right-to-left (RTL) locales, such as those using Arabic or Hebrew scripts. When enabled, this property ensures proper alignment and rendering for languages that read from right to left."boolean

Gets or sets a value that determines whether the element’s layout and text direction are aligned for right-to-left (RTL) locales, such as those using Arabic or Hebrew scripts. When enabled, this property ensures proper alignment and rendering for languages that read from right to left."

Default value

false
Try a demo showcasing the rightToLeft property.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

<smart-button-group right-to-left></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.rightToLeft = true;

Read the current value:

const el = document.querySelector('smart-button-group');
const rightToLeft = el.rightToLeft;

selectedIndexesGets or sets the indexes of the selected buttons within the group as an array of numbers. Each number corresponds to the zero-based index of a selected button. Used to track multiple selected buttons within the group. number[]

Gets or sets the indexes of the selected buttons within the group as an array of numbers. Each number corresponds to the zero-based index of a selected button. Used to track multiple selected buttons within the group.

Try a demo showcasing the selectedIndexes property.

Examples

Markup and runtime examples for selectedIndexes:

HTML:

<smart-button-group selected-indexes="[1,2,3]"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.selectedIndexes = [0];

Read the current value:

const el = document.querySelector('smart-button-group');
const selectedIndexes = el.selectedIndexes;

selectedValuesGets or sets the selected values of the button group component as an array of strings. Each string in the array corresponds to the value attribute of a selected button within the group. This property can be used to programmatically read which buttons are currently selected or to define the initial selection state. string[]

Gets or sets the selected values of the button group component as an array of strings. Each string in the array corresponds to the value attribute of a selected button within the group. This property can be used to programmatically read which buttons are currently selected or to define the initial selection state.

Try a demo showcasing the selectedValues property.

Examples

Markup and runtime examples for selectedValues:

HTML:

<smart-button-group selected-values="["item 1"]"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.selectedValues = ["item 1", "item 2"];

Read the current value:

const el = document.querySelector('smart-button-group');
const selectedValues = el.selectedValues;

selectionModeSpecifies how items within the element can be selected—for example, allowing single selection, multiple selections, or no selection at all."none" | "one" | "zeroOrOne" | "zeroOrMany"

Specifies how items within the element can be selected—for example, allowing single selection, multiple selections, or no selection at all.

Allowed Values

  • "none" - The element does not allow selection.
  • "one" - The element allows one item to be selected. One item must always be selected.
  • "zeroOrOne" - The element allows one or zero items to be selected.
  • "zeroOrMany" - The element allows zero or many items to be selected.

Default value

"one"
Try a demo showcasing the selectionMode property.

Examples

Markup and runtime examples for selectionMode:

HTML:

<smart-button-group selection-mode="zeroOrOne"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.selectionMode = "zeroOrMany";

Read the current value:

const el = document.querySelector('smart-button-group');
const selectionMode = el.selectionMode;

themeSpecifies the visual theme to be applied to the element. The theme controls the overall appearance, including colors, typography, and style variations, ensuring the element is displayed consistently according to the selected design.string

Specifies the visual theme to be applied to the element. The theme controls the overall appearance, including colors, typography, and style variations, ensuring the element is displayed consistently according to the selected design.

Default value

""
Try a demo showcasing the theme property.

Examples

Markup and runtime examples for theme:

HTML:

<smart-button-group theme="blue"></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.theme = "red";

Read the current value:

const el = document.querySelector('smart-button-group');
const theme = el.theme;

unfocusableIf set to true, this property prevents the element from receiving keyboard focus, making it unreachable via keyboard navigation (such as the Tab key).boolean

If set to true, this property prevents the element from receiving keyboard focus, making it unreachable via keyboard navigation (such as the Tab key).

Default value

false

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

<smart-button-group unfocusable></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.unfocusable = false;

Read the current value:

const el = document.querySelector('smart-button-group');
const unfocusable = el.unfocusable;

unlockKeyDefines or retrieves the unlockKey, a unique identifier or code required to activate and gain access to the product’s full features.string

Defines or retrieves the unlockKey, a unique identifier or code required to activate and gain access to the product’s full features.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

<smart-button-group unlock-key=""></smart-button-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-button-group');
el.unlockKey = "1111-2222-3333-4444-5555";

Read the current value:

const el = document.querySelector('smart-button-group');
const unlockKey = el.unlockKey;

Events

changeThe "change" event is triggered whenever the values of selectedValues or selectedIndexes are updated. This event occurs whenever the user selects or deselects an option, or when the selection state is modified programmatically. Use this event to respond to changes in the selection, such as updating the UI or performing validation.CustomEvent

The "change" event is triggered whenever the values of selectedValues or selectedIndexes are updated. This event occurs whenever the user selects or deselects an option, or when the selection state is modified programmatically. Use this event to respond to changes in the selection, such as updating the UI or performing validation.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onChange

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the change event.

Examples

Listen for change using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-button-group')?.addEventListener('change', (event) => {
	// event handling code goes here.
})

Methods

select( value: number | string): voidToggles the selection state of an item within the element, allowing users to either select or deselect the specified item based on its current state.

Toggles the selection state of an item within the element, allowing users to either select or deselect the specified item based on its current state.

Arguments

valuenumber | string

The index or the value of the item to be selected/unselected.

On the custom element in the DOM (narrow the selector, e.g. to #my-buttongroup, if you host multiple widgets):

document.querySelector('smart-button-group')?.select("'a'","0");

Try a demo showcasing the select method.

CSS Variables

--smart-button-text-transformvar()

Default value

"uppercase"

Controls the capitalization of the item's text. Could be set as uppercase/lowercase/capitalize.

--smart-button-paddingvar()

Default value

"8px 16px"

Sets the ButtonGroup items's paddings.