ButtonGroup JAVASCRIPT UI Component API

ButtonGroup Javascript API

Class

ButtonGroup

ButtonGroup

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

Selector

smart-button-group

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.
SselectionModeSpecifies how items within the element can be selected—for example, allowing single selection, multiple selections, or no selection at all.
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.
UunlockKeyDefines or retrieves the unlockKey, a unique identifier or code required to activate and gain access to the product’s full features.
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."
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.
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.
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.
UunfocusableIf set to true, this property prevents the element from receiving keyboard focus, making it unreachable via keyboard navigation (such as the Tab key).

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

animation"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"

Example

Set the animation property. 

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

Set the animation property by using the HTML Element's instance. 

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

Get the animation property. 

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

dataSourceany

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.

Example

Set the dataSource property. 

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

Set the dataSource property by using the HTML Element's instance. 

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

Get the dataSource property. 

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

selectionMode"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.

Example

Set the selectionMode property. 

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

Set the selectionMode property by using the HTML Element's instance. 

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

Get the selectionMode property. 

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

disabledboolean

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

Example

Set the disabled property. 

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

Set the disabled property by using the HTML Element's instance. 

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

Get the disabled property. 

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

unlockKeystring

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

Default value

""

Example

Set the unlockKey property. 

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

Set the unlockKey property by using the HTML Element's instance. 

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

Get the unlockKey property. 

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

localestring

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"

Example

Set the locale property. 

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

Set the locale property by using the HTML Element's instance. 

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

Get the locale property. 

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

localizeFormatFunctionfunction | 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.

Example

Set the localizeFormatFunction property. 

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

Set the localizeFormatFunction property by using the HTML Element's instance. 

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

Get the localizeFormatFunction property. 

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

messagesobject

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."

}

Example

Set the messages property. 

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

Set the messages property by using the HTML Element's instance. 

 const buttongroup = document.querySelector('smart-button-group');
 buttongroup.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."}};

Get the messages property. 

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

namestring

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

""""

Example

Set the name property. 

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

Set the name property by using the HTML Element's instance. 

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

Get the name property. 

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

readonlyboolean

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

Example

Set the readonly property. 

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

Set the readonly property by using the HTML Element's instance. 

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

Get the readonly property. 

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

rightToLeftboolean

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.

Example

Set the rightToLeft property. 

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

Set the rightToLeft property by using the HTML Element's instance. 

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

Get the rightToLeft property. 

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

themestring

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

""

Example

Set the theme property. 

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

Set the theme property by using the HTML Element's instance. 

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

Get the theme property. 

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

selectedValuesstring[]

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.

Example

Set the selectedValues property. 

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

Set the selectedValues property by using the HTML Element's instance. 

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

Get the selectedValues property. 

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

selectedIndexesnumber[]

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.

Example

Set the selectedIndexes property. 

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

Set the selectedIndexes property by using the HTML Element's instance. 

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

Get the selectedIndexes property. 

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

unfocusableboolean

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

Example

Set the unfocusable property. 

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

Set the unfocusable property by using the HTML Element's instance. 

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

Get the unfocusable property. 

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

Events

changeCustomEvent

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.

Example

Set up the event handler of change event. 

const buttongroup = document.querySelector('smart-button-group');
buttongroup.addEventListener('change', function (event) {
	// event handling code goes here.
})

Methods

select( value: number | string): void

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.


Invoke the select method.

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

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.