Button — Smart UI JavaScript API

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

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

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

      el.innerHTML = 'Button';

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

Developer Quick Reference

Component: Button   Framework: JavaScript   Selector: smart-button

API counts: 16 properties, 0 methods, 1 events

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

Common methods: n/a

Common events: click

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

Buttons allow users to take actions, and make choices, with a single tap. Buttons communicate actions that users can take.

Class

Button

Button

Buttons allow users to take actions, and make choices, with a single tap. Buttons communicate actions that users can take.

Selector

smart-button

Quick picks

clickdisabledvalue

Properties

AanimationSpecifies the animation mode for the element. When set to 'none', all animations are disabled. Use this property to enable, disable, or customize the animation behavior as needed. You can get the current animation mode or assign a new value to control how animations are applied.
CclickModeSpecifies how the element responds to user click interactions, such as triggering specific actions, toggling states, or initiating custom event handling based on the selected mode.
CcontentSpecifies the inner content of the element, such as text, HTML, or child elements, determining what is displayed inside the element on the web page.
DdisabledDetermines whether the button is interactive. When enabled ('true'), users can click and interact with the button. When disabled ('false'), the button appears inactive and does not respond to user actions.
IinnerHTMLUpdates the contents of the element by setting its inner HTML to the specified value. This replaces all existing child elements and text within the element with the provided HTML markup. Use caution when inserting user-generated content to avoid security risks such as cross-site scripting (XSS).
LlocaleSpecifies the language code to use for retrieving or displaying messages. When set, it determines which localized message set from the messages property is used. Getting this property returns the current language code. Typically used for enabling multi-language support within the application.
LlocalizeFormatFunctionA callback function that allows you to define or modify the formatting of messages returned by the Localization Module. Use this callback to customize how localized messages are structured or displayed before they are delivered to your application.
MmessagesDefines or retrieves an object containing localized strings for the widget's user interface. This property allows you to customize text displayed by the widget for different languages and regions, and works in conjunction with the locale property to ensure proper localization.
NnameDefines or retrieves the name attribute of the element. The name attribute uniquely identifies form elements when submitting data through an HTML form, allowing the server to associate input values with their corresponding fields. This attribute is essential for processing form data correctly.
RreadonlyIf the custom element is set to readonly, users will not be able to modify its value or content through direct interaction (such as typing, selecting, or dragging). However, the element may still be focusable and its value can be changed programmatically via scripts. User-initiated actions that would normally alter its state are disabled.
RrightToLeftGets or sets a value that determines whether the element's alignment supports right-to-left (RTL) text direction, which is typically used by languages such as Arabic or Hebrew. When enabled, the element is properly aligned to display content for RTL locales.
TthemeSpecifies the visual theme applied to the element, which controls its overall appearance, including colors, fonts, and styling. This property allows you to select a predefined look and feel for the element.
TtypeSpecifies or retrieves the button's type attribute, which determines the button's behavior—such as "submit" to submit a form, "reset" to reset form fields, or "button" for a general-purpose clickable button.
UunfocusableWhen set to true, this property prevents the element from receiving keyboard focus, making it impossible for users to select the element using the Tab key or other navigation methods.
UunlockKeyHandles the retrieval or assignment of the 'unlockKey', a unique value required to authorize and unlock access to the product's features or content.
VvalueSets or retrieves the button's value attribute, which typically defines the text displayed on the button or the value submitted when the button is used in a form.

Events

CclickThe click event is triggered based on the selected clickMode, meaning the event behavior will vary depending on the current setting of the clickMode property.

Properties

animationSpecifies the animation mode for the element. When set to 'none', all animations are disabled. Use this property to enable, disable, or customize the animation behavior as needed. You can get the current animation mode or assign a new value to control how animations are applied."none" | "simple" | "advanced"

Specifies the animation mode for the element. When set to 'none', all animations are disabled. Use this property to enable, disable, or customize the animation behavior as needed. You can get the current animation mode or assign a new value to control how animations are applied.

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-button animation="none"></smart-button>

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

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

Read the current value:

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

clickModeSpecifies how the element responds to user click interactions, such as triggering specific actions, toggling states, or initiating custom event handling based on the selected mode."hover" | "press" | "release" | "pressAndRelease"

Specifies how the element responds to user click interactions, such as triggering specific actions, toggling states, or initiating custom event handling based on the selected mode.

Allowed Values

  • "hover" - The element fires a click event when hovered.
  • "press" - The element fires a click event when pressed.
  • "release" - The element fires a click event when released.
  • "pressAndRelease" - The element fires a click event when pressed and again when released.

Default value

"release"

Examples

Markup and runtime examples for clickMode:

HTML:

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

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

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

Read the current value:

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

contentSpecifies the inner content of the element, such as text, HTML, or child elements, determining what is displayed inside the element on the web page.any

Specifies the inner content of the element, such as text, HTML, or child elements, determining what is displayed inside the element on the web page.

Default value

""
Try a demo showcasing the content property.

Examples

Markup and runtime examples for content:

HTML:

<smart-button content="Button Label"></smart-button>

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

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

Read the current value:

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

disabledDetermines whether the button is interactive. When enabled ('true'), users can click and interact with the button. When disabled ('false'), the button appears inactive and does not respond to user actions.boolean

Determines whether the button is interactive. When enabled ('true'), users can click and interact with the button. When disabled ('false'), the button appears inactive and does not respond to user actions.

Default value

false
Try a demo showcasing the disabled property.

Examples

Markup and runtime examples for disabled:

HTML attribute:

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

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

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

Read the current value:

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

innerHTMLUpdates the contents of the element by setting its inner HTML to the specified value. This replaces all existing child elements and text within the element with the provided HTML markup. Use caution when inserting user-generated content to avoid security risks such as cross-site scripting (XSS).string

Updates the contents of the element by setting its inner HTML to the specified value. This replaces all existing child elements and text within the element with the provided HTML markup. Use caution when inserting user-generated content to avoid security risks such as cross-site scripting (XSS).

Default value

""""
Try a demo showcasing the innerHTML property.

Examples

Markup and runtime examples for innerHTML:

HTML:

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

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

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

Read the current value:

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

localeSpecifies the language code to use for retrieving or displaying messages. When set, it determines which localized message set from the messages property is used. Getting this property returns the current language code. Typically used for enabling multi-language support within the application.string

Specifies the language code to use for retrieving or displaying messages. When set, it determines which localized message set from the messages property is used. Getting this property returns the current language code. Typically used for enabling multi-language support within the application.

Default value

"en"

Examples

Markup and runtime examples for locale:

HTML:

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

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

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

Read the current value:

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

localizeFormatFunctionA callback function that allows you to define or modify the formatting of messages returned by the Localization Module. Use this callback to customize how localized messages are structured or displayed before they are delivered to your application.function | null

A callback function that allows you to define or modify the formatting of messages returned by the Localization Module. Use this callback to customize how localized messages are structured or displayed before they are delivered to your application.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

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

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

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

Read the current value:

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

messagesDefines or retrieves an object containing localized strings for the widget's user interface. This property allows you to customize text displayed by the widget for different languages and regions, and works in conjunction with the locale property to ensure proper localization.object

Defines or retrieves an object containing localized strings for the widget's user interface. This property allows you to customize text displayed by the widget for different languages and regions, and works in conjunction with the locale property to ensure proper localization.

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

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

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

nameDefines or retrieves the name attribute of the element. The name attribute uniquely identifies form elements when submitting data through an HTML form, allowing the server to associate input values with their corresponding fields. This attribute is essential for processing form data correctly.string

Defines or retrieves the name attribute of the element. The name attribute uniquely identifies form elements when submitting data through an HTML form, allowing the server to associate input values with their corresponding fields. This attribute is essential for processing form data correctly.

Default value

""""
Try a demo showcasing the name property.

Examples

Markup and runtime examples for name:

HTML:

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

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

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

Read the current value:

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

readonlyIf the custom element is set to readonly, users will not be able to modify its value or content through direct interaction (such as typing, selecting, or dragging). However, the element may still be focusable and its value can be changed programmatically via scripts. User-initiated actions that would normally alter its state are disabled.boolean

If the custom element is set to readonly, users will not be able to modify its value or content through direct interaction (such as typing, selecting, or dragging). However, the element may still be focusable and its value can be changed programmatically via scripts. User-initiated actions that would normally alter its state are disabled.

Default value

false

Examples

Markup and runtime examples for readonly:

HTML attribute:

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

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

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

Read the current value:

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

rightToLeftGets or sets a value that determines whether the element's alignment supports right-to-left (RTL) text direction, which is typically used by languages such as Arabic or Hebrew. When enabled, the element is properly aligned to display content for RTL locales.boolean

Gets or sets a value that determines whether the element's alignment supports right-to-left (RTL) text direction, which is typically used by languages such as Arabic or Hebrew. When enabled, the element is properly aligned to display content for RTL locales.

Default value

false
Try a demo showcasing the rightToLeft property.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

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

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

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

Read the current value:

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

themeSpecifies the visual theme applied to the element, which controls its overall appearance, including colors, fonts, and styling. This property allows you to select a predefined look and feel for the element.string

Specifies the visual theme applied to the element, which controls its overall appearance, including colors, fonts, and styling. This property allows you to select a predefined look and feel for the element.

Default value

""
Try a demo showcasing the theme property.

Examples

Markup and runtime examples for theme:

HTML:

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

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

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

Read the current value:

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

typeSpecifies or retrieves the button's type attribute, which determines the button's behavior—such as "submit" to submit a form, "reset" to reset form fields, or "button" for a general-purpose clickable button.string

Specifies or retrieves the button's type attribute, which determines the button's behavior—such as "submit" to submit a form, "reset" to reset form fields, or "button" for a general-purpose clickable button.

Default value

"Reset"
Try a demo showcasing the type property.

Examples

Markup and runtime examples for type:

HTML:

<smart-button type="submit"></smart-button>

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

const el = document.querySelector('smart-button');
el.type = "reset";

Read the current value:

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

unfocusableWhen set to true, this property prevents the element from receiving keyboard focus, making it impossible for users to select the element using the Tab key or other navigation methods.boolean

When set to true, this property prevents the element from receiving keyboard focus, making it impossible for users to select the element using the Tab key or other navigation methods.

Default value

false

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

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

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

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

Read the current value:

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

unlockKeyHandles the retrieval or assignment of the 'unlockKey', a unique value required to authorize and unlock access to the product's features or content.string

Handles the retrieval or assignment of the 'unlockKey', a unique value required to authorize and unlock access to the product's features or content.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

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

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

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

Read the current value:

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

valueSets or retrieves the button's value attribute, which typically defines the text displayed on the button or the value submitted when the button is used in a form.string

Sets or retrieves the button's value attribute, which typically defines the text displayed on the button or the value submitted when the button is used in a form.

Default value

""
Try a demo showcasing the value property.

Examples

Markup and runtime examples for value:

HTML:

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

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

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

Read the current value:

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

Events

clickThe click event is triggered based on the selected clickMode, meaning the event behavior will vary depending on the current setting of the clickMode property.CustomEvent

The click event is triggered based on the selected clickMode, meaning the event behavior will vary depending on the current setting of the clickMode property.

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

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 click event.

Examples

Listen for click 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')?.addEventListener('click', (event) => {
	// event handling code goes here.
})

CSS Variables

--smart-button-text-transformvar()

Default value

"uppercase"

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

--smart-button-paddingvar()

Default value

"8px 16px"

Sets button's paddings.

--smart-button-large-paddingvar()

Default value

"10px 16px"

Sets large button's paddings.

--smart-button-large-font-sizevar()

Default value

"18px"

Sets large button's font size.

--smart-button-small-paddingvar()

Default value

"5px 10px"

Sets small button's paddings.

--smart-button-small-font-sizevar()

Default value

"12px"

Sets small button's font size.

--smart-button-very-small-paddingvar()

Default value

"1px 5px"

Sets very small button's paddings.

--smart-button-very-small-font-sizevar()

Default value

"12px"

Sets very small button's font size.

--smart-button-flat-colorvar()

Default value

"var(--smart-background-color)"

The color of the flat button.

--smart-button-outlined-colorvar()

Default value

"var(--smart-background-color)"

The color of the outlined button.

--smart-button-outlined-bordervar()

Default value

"var(--smart-border)"

The border of the outlined button.