ToggleButton — Smart UI JavaScript API

ToggleButton — 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>ToggleButton - JavaScript Quick Start</title>
  <link rel="stylesheet" href="./node_modules/smart-webcomponents/source/styles/smart.default.css" />
</head>
<body>
  <smart-toggle-button id="demo-togglebutton">Save</smart-toggle-button>

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

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

      el.checked = true;
      el.innerHTML = 'Toggle Button';

      el.addEventListener('click', () => console.log('Button clicked'));
    }
  </script>
</body>
</html>
For AI tooling

Developer Quick Reference

Component: ToggleButton   Framework: JavaScript   Selector: smart-toggle-button

API counts: 14 properties, 0 methods, 3 events

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

Common methods: n/a

Common events: change, checkValue, uncheckValue

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

ToggleButton allows the user to change a setting between two states.

Class

ToggleButton

ToggleButton

ToggleButton allows the user to change a setting between two states.

Selector

smart-toggle-button

Quick picks

changedisabledvalue

Properties

AanimationSpecifies or retrieves the current animation mode for the element. When set to 'none', all animations are disabled, and the element will appear or update instantly without any animated transitions. If a different value is assigned, the element will use the corresponding animation effect during state changes.
CcheckedDefines or updates the current state of the element, controlling its behavior, appearance, or functionality based on the specified value. This property determines how the element responds to user interactions and can trigger associated changes in the interface or underlying logic.
CclickModeSpecifies how the button responds to user click interactions, determining the trigger conditions for its click event (e.g., on mouse down, on mouse up, or after a complete click).
DdisabledDetermines whether the ratio button is displayed and interactive. Set to true to show and enable the button, or false to hide and disable it.
IinnerHTMLAssigns the specified HTML markup to the element’s content, replacing all existing child elements and text within the element. This allows dynamic insertion of HTML structure and content inside the targeted element.
LlocaleSpecifies or retrieves the current language setting. This property works together with the messages property to determine which localized messages are displayed. When you set this property, the component selects the appropriate set of messages corresponding to the chosen language.
LlocalizeFormatFunctionCallback function associated with the localization module, typically used to handle events or operations such as language changes, text translations, or localization updates within the application.
MmessagesSets or retrieves an object containing the text strings displayed in the widget, allowing for easy localization and customization of interface messages. This property works together with the locale property to provide translations and adapt the widget's language to different regions. Use this object to define or override the default text for various UI elements, tooltips, messages, and labels within the widget.
NnameGets or assigns the name of the widget. This property allows you to retrieve the current name of the widget or specify a new name for identification and reference purposes within the application.
RreadonlyIf the custom element has the 'readonly' attribute set, its content cannot be modified by the user. However, users may still be able to interact with the element in other ways, such as selecting or copying its content. No input changes or value modifications are permitted while the element is in the readonly state.
TthemeSpecifies the theme to be applied. The selected theme controls the visual appearance and styling of the element, including colors, fonts, spacing, and other design-related properties.
UunfocusableWhen set to true, the element will be removed from the tab order and cannot receive focus via keyboard or mouse interactions.
UunlockKeySets or retrieves the value of the unlockKey, a unique code or token required to authorize and unlock access to the product’s features or functionality.
VvalueGets the current value of the widget or sets a new value for the widget. Use this property to retrieve what the widget currently holds or to update it programmatically.

Events

CchangeThis event is triggered whenever the state of the widget changes—specifically, when the user checks or unchecks the widget. It allows you to respond to any change in the widget’s selection status.
CcheckValueThis event is triggered whenever the widget transitions into a checked state, such as when a user selects or activates it. It allows developers to respond to changes in the widget's selection status.
UuncheckValueThis event is triggered when the user deselects or unchecks the widget, typically by clicking or tapping on it. It indicates that the widget has transitioned from a checked or selected state to an unchecked or unselected state. Developers can use this event to execute custom logic or update the application’s interface in response to the change.

Properties

animationSpecifies or retrieves the current animation mode for the element. When set to 'none', all animations are disabled, and the element will appear or update instantly without any animated transitions. If a different value is assigned, the element will use the corresponding animation effect during state changes."none" | "simple" | "advanced"

Specifies or retrieves the current animation mode for the element. When set to 'none', all animations are disabled, and the element will appear or update instantly without any animated transitions. If a different value is assigned, the element will use the corresponding animation effect during state changes.

Allowed Values

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

Default value

"advanced"

Examples

Markup and runtime examples for animation:

HTML:

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

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

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

Read the current value:

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

checkedDefines or updates the current state of the element, controlling its behavior, appearance, or functionality based on the specified value. This property determines how the element responds to user interactions and can trigger associated changes in the interface or underlying logic.boolean

Defines or updates the current state of the element, controlling its behavior, appearance, or functionality based on the specified value. This property determines how the element responds to user interactions and can trigger associated changes in the interface or underlying logic.

Default value

false
Try a demo showcasing the checked property.

Examples

Markup and runtime examples for checked:

HTML attribute:

<smart-toggle-button checked></smart-toggle-button>

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

const el = document.querySelector('smart-toggle-button');
el.checked = false;

Read the current value:

const el = document.querySelector('smart-toggle-button');
const checked = el.checked;

clickModeSpecifies how the button responds to user click interactions, determining the trigger conditions for its click event (e.g., on mouse down, on mouse up, or after a complete click)."hover" | "press" | "release" | "pressAndRelease"

Specifies how the button responds to user click interactions, determining the trigger conditions for its click event (e.g., on mouse down, on mouse up, or after a complete click).

Default value

"release"

Examples

Markup and runtime examples for clickMode:

HTML:

<smart-toggle-button click-mode="hover"></smart-toggle-button>

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

const el = document.querySelector('smart-toggle-button');
el.clickMode = "release";

Read the current value:

const el = document.querySelector('smart-toggle-button');
const clickMode = el.clickMode;

disabledDetermines whether the ratio button is displayed and interactive. Set to true to show and enable the button, or false to hide and disable it.boolean

Determines whether the ratio button is displayed and interactive. Set to true to show and enable the button, or false to hide and disable it.

Default value

false

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-toggle-button disabled></smart-toggle-button>

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

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

Read the current value:

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

innerHTMLAssigns the specified HTML markup to the element’s content, replacing all existing child elements and text within the element. This allows dynamic insertion of HTML structure and content inside the targeted element.string

Assigns the specified HTML markup to the element’s content, replacing all existing child elements and text within the element. This allows dynamic insertion of HTML structure and content inside the targeted element.

Default value

""""

Examples

Markup and runtime examples for innerHTML:

HTML:

<smart-toggle-button inner-h-t-m-l="Toggle Button Label"></smart-toggle-button>

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

const el = document.querySelector('smart-toggle-button');
el.innerHTML = "New Toggle Button Label";

Read the current value:

const el = document.querySelector('smart-toggle-button');
const innerHTML = el.innerHTML;

localeSpecifies or retrieves the current language setting. This property works together with the messages property to determine which localized messages are displayed. When you set this property, the component selects the appropriate set of messages corresponding to the chosen language.string

Specifies or retrieves the current language setting. This property works together with the messages property to determine which localized messages are displayed. When you set this property, the component selects the appropriate set of messages corresponding to the chosen language.

Default value

"en"

Examples

Markup and runtime examples for locale:

HTML:

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

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

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

Read the current value:

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

localizeFormatFunctionCallback function associated with the localization module, typically used to handle events or operations such as language changes, text translations, or localization updates within the application.function | null

Callback function associated with the localization module, typically used to handle events or operations such as language changes, text translations, or localization updates within the application.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

<smart-toggle-button localize-format-function="function(){return '...'}"></smart-toggle-button>

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

const el = document.querySelector('smart-toggle-button');
el.localizeFormatFunction = "function(){return '...'}";

Read the current value:

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

messagesSets or retrieves an object containing the text strings displayed in the widget, allowing for easy localization and customization of interface messages. This property works together with the locale property to provide translations and adapt the widget's language to different regions. Use this object to define or override the default text for various UI elements, tooltips, messages, and labels within the widget.object

Sets or retrieves an object containing the text strings displayed in the widget, allowing for easy localization and customization of interface messages. This property works together with the locale property to provide translations and adapt the widget's language to different regions. Use this object to define or override the default text for various UI elements, tooltips, messages, and labels within the widget.

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

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

const el = document.querySelector('smart-toggle-button');
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-toggle-button');
const messages = el.messages;

nameGets or assigns the name of the widget. This property allows you to retrieve the current name of the widget or specify a new name for identification and reference purposes within the application.string

Gets or assigns the name of the widget. This property allows you to retrieve the current name of the widget or specify a new name for identification and reference purposes within the application.

Default value

""""

Examples

Markup and runtime examples for name:

HTML:

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

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

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

Read the current value:

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

readonlyIf the custom element has the 'readonly' attribute set, its content cannot be modified by the user. However, users may still be able to interact with the element in other ways, such as selecting or copying its content. No input changes or value modifications are permitted while the element is in the readonly state.boolean

If the custom element has the 'readonly' attribute set, its content cannot be modified by the user. However, users may still be able to interact with the element in other ways, such as selecting or copying its content. No input changes or value modifications are permitted while the element is in the readonly state.

Default value

false

Examples

Markup and runtime examples for readonly:

HTML attribute:

<smart-toggle-button readonly></smart-toggle-button>

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

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

Read the current value:

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

themeSpecifies the theme to be applied. The selected theme controls the visual appearance and styling of the element, including colors, fonts, spacing, and other design-related properties.string

Specifies the theme to be applied. The selected theme controls the visual appearance and styling of the element, including colors, fonts, spacing, and other design-related properties.

Default value

""

Examples

Markup and runtime examples for theme:

HTML:

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

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

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

Read the current value:

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

unfocusableWhen set to true, the element will be removed from the tab order and cannot receive focus via keyboard or mouse interactions.boolean

When set to true, the element will be removed from the tab order and cannot receive focus via keyboard or mouse interactions.

Default value

false

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

<smart-toggle-button unfocusable></smart-toggle-button>

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

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

Read the current value:

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

unlockKeySets or retrieves the value of the unlockKey, a unique code or token required to authorize and unlock access to the product’s features or functionality.string

Sets or retrieves the value of the unlockKey, a unique code or token required to authorize and unlock access to the product’s features or functionality.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

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

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

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

Read the current value:

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

valueGets the current value of the widget or sets a new value for the widget. Use this property to retrieve what the widget currently holds or to update it programmatically.string

Gets the current value of the widget or sets a new value for the widget. Use this property to retrieve what the widget currently holds or to update it programmatically.

Default value

""""

Examples

Markup and runtime examples for value:

HTML:

<smart-toggle-button value="Value"></smart-toggle-button>

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

const el = document.querySelector('smart-toggle-button');
el.value = "New Value";

Read the current value:

const el = document.querySelector('smart-toggle-button');
const value = el.value;

Events

changeThis event is triggered whenever the state of the widget changes—specifically, when the user checks or unchecks the widget. It allows you to respond to any change in the widget’s selection status.CustomEvent

This event is triggered whenever the state of the widget changes—specifically, when the user checks or unchecks the widget. It allows you to respond to any change in the widget’s selection status.

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

Arguments

evCustomEvent
ev.detailObject
ev.detail.value - A boolean value indicating the new state of the button ( checked or not ).
ev.detail.oldValue - A boolean value indicating the previous state of the button ( checked or not ).
ev.detail.changeType - A string flag indicating whether the change event was triggered via API or an event.

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.

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-toggle-button')?.addEventListener('change', (event) => {
    const detail = event.detail,
        value = detail.value,
        oldValue = detail.oldValue,
        changeType = detail.changeType;

	// event handling code goes here.
})

checkValueThis event is triggered whenever the widget transitions into a checked state, such as when a user selects or activates it. It allows developers to respond to changes in the widget's selection status.CustomEvent

This event is triggered whenever the widget transitions into a checked state, such as when a user selects or activates it. It allows developers to respond to changes in the widget's selection status.

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

Arguments

evCustomEvent
ev.detailObject
ev.detail.changeType - A string flag indicating whether the change event was triggered via API or an event.

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.

Examples

Listen for checkValue 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-toggle-button')?.addEventListener('checkValue', (event) => {
    const detail = event.detail,
        changeType = detail.changeType;

	// event handling code goes here.
})

uncheckValueThis event is triggered when the user deselects or unchecks the widget, typically by clicking or tapping on it. It indicates that the widget has transitioned from a checked or selected state to an unchecked or unselected state. Developers can use this event to execute custom logic or update the application’s interface in response to the change.CustomEvent

This event is triggered when the user deselects or unchecks the widget, typically by clicking or tapping on it. It indicates that the widget has transitioned from a checked or selected state to an unchecked or unselected state. Developers can use this event to execute custom logic or update the application’s interface in response to the change.

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

Arguments

evCustomEvent
ev.detailObject
ev.detail.changeType - A string flag indicating whether the change event was triggered via API or an event.

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.

Examples

Listen for uncheckValue 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-toggle-button')?.addEventListener('uncheckValue', (event) => {
    const detail = event.detail,
        changeType = detail.changeType;

	// event handling code goes here.
})