CheckBox — Smart UI JavaScript API

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

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

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

      el.checked = true;
      el.innerHTML = 'Enable notifications';

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

Developer Quick Reference

Component: CheckBox   Framework: JavaScript   Selector: smart-check-box

API counts: 16 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.checkbox.js

Checkbox is a component used for allowing a user to make a multiple choice. Broadly used in the forms and surveys.

Class

CheckBox

CheckBox

Checkbox is a component used for allowing a user to make a multiple choice. Broadly used in the forms and surveys.

Selector

smart-check-box

Quick picks

changedisabledvalue

Properties

AanimationSpecifies the animation mode for the component. You can retrieve the current mode or assign a new one. Setting this property to 'none' will disable all animations; assigning other valid values will enable the corresponding animation effects.
CcheckedSets or retrieves the checked state of the component. If set to true, the component appears checked (selected); if false, it appears unchecked. Useful for managing selection or toggle controls such as checkboxes or radio buttons.
CcheckModeSpecifies the area or region of the element that users can interact with to expand, collapse, or toggle its state. This property defines which part of the element responds to toggle actions, such as clicks or taps.
CclickModeSpecifies how the checkbox responds to user click interactions, such as toggling its checked state or triggering related events.
DdisabledDetermines whether the checkbox is interactive or not. When set to true, the checkbox is enabled and the user can select or deselect it. When set to false, the checkbox is disabled, preventing any user interaction.
IinnerHTMLSets or retrieves the HTML markup contained within the element. When set, it updates the element’s contents by parsing the specified HTML string and replacing any existing child nodes. When accessed, it returns a string representing the element’s current HTML content.
LlocaleSets or retrieves the current language code (e.g., 'en', 'fr') used for localization. This property works together with the messages property to select and display the appropriate set of localized messages based on the specified language.
LlocalizeFormatFunctionA callback function that allows you to define a custom formatting logic for messages returned by the Localization Module. Use this to adjust message content, structure, or variables before the final output is presented to the user.
MmessagesDefines or retrieves an object containing localized strings used throughout the widget’s interface. This property allows you to customize the text displayed by the widget for different languages or regions. It works in conjunction with the locale property, which determines the current language, ensuring that the appropriate set of strings is applied based on the selected locale.
NnameSets or retrieves the value of the element’s name attribute. The name attribute identifies form elements when submitting HTML forms, allowing their values to be sent to the server as key-value pairs. This is essential for server-side processing of form data.
RreadonlyWhen the element is set to readonly, users can view its content but are unable to modify or edit it. However, the element may still receive focus and allow text selection or copying, depending on the element's type and browser behavior. User interaction that changes the value or state of the element is disabled.
RrightToLeftGets or sets a value that determines whether the element’s layout is aligned to support right-to-left (RTL) languages, such as Arabic or Hebrew, ensuring proper text direction and alignment for users in those locales.
TthemeSpecifies the theme to be applied to the element. The selected theme controls the element’s visual appearance, including colors, fonts, and overall style, ensuring a consistent and cohesive look throughout the interface.
UunfocusableWhen set to true, the element is rendered non-focusable, meaning it cannot receive keyboard or programmatic focus. This prevents users from navigating to the element using the keyboard (e.g., with the Tab key) or through scripts.
UunlockKeySpecifies or retrieves the unlockKey used to activate or grant access to the product. This key serves as a security credential required to unlock and use the product’s features.
VvalueRetrieves the current value of the element or assigns a new value to it. This property allows you to programmatically read or update the element’s value—for example, reading user input from a form field or setting a default value dynamically.

Events

CchangeThis event is triggered whenever the widget's checked state changes, such as when the user selects or deselects (checks or unchecks) the widget. It allows you to respond dynamically whenever the widget transitions between checked and unchecked states.
CcheckValueThis event is triggered whenever the widget's checked state changes from unchecked to checked, such as when a user selects or activates the widget. It allows you to execute custom logic in response to the widget being checked.
UuncheckValueThis event is triggered whenever the widget transitions from a checked (selected) state to an unchecked (deselected) state, indicating that the user has cleared or deselected the widget (e.g., by unchecking a checkbox or turning off a toggle switch).

Properties

animationSpecifies the animation mode for the component. You can retrieve the current mode or assign a new one. Setting this property to 'none' will disable all animations; assigning other valid values will enable the corresponding animation effects."none" | "simple" | "advanced"

Specifies the animation mode for the component. You can retrieve the current mode or assign a new one. Setting this property to 'none' will disable all animations; assigning other valid values will enable the corresponding animation effects.

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

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

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

Read the current value:

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

checkedSets or retrieves the checked state of the component. If set to true, the component appears checked (selected); if false, it appears unchecked. Useful for managing selection or toggle controls such as checkboxes or radio buttons.boolean

Sets or retrieves the checked state of the component. If set to true, the component appears checked (selected); if false, it appears unchecked. Useful for managing selection or toggle controls such as checkboxes or radio buttons.

Default value

false
Try a demo showcasing the checked property.

Examples

Markup and runtime examples for checked:

HTML attribute:

<smart-check-box checked></smart-check-box>

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

const el = document.querySelector('smart-check-box');
el.checked = false;

Read the current value:

const el = document.querySelector('smart-check-box');
const checked = el.checked;

checkModeSpecifies the area or region of the element that users can interact with to expand, collapse, or toggle its state. This property defines which part of the element responds to toggle actions, such as clicks or taps."both" | "input" | "label"

Specifies the area or region of the element that users can interact with to expand, collapse, or toggle its state. This property defines which part of the element responds to toggle actions, such as clicks or taps.

Allowed Values

  • "both" - Both the label and input can be used to toggle the state of the element.
  • "input" - Only the input can be used to toggle the state of the element.
  • "label" - Only the label can be used to toggle the state of the element.

Default value

"both"

Examples

Markup and runtime examples for checkMode:

HTML:

<smart-check-box check-mode="input"></smart-check-box>

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

const el = document.querySelector('smart-check-box');
el.checkMode = "label";

Read the current value:

const el = document.querySelector('smart-check-box');
const checkMode = el.checkMode;

clickModeSpecifies how the checkbox responds to user click interactions, such as toggling its checked state or triggering related events."press" | "release" | "pressAndRelease"

Specifies how the checkbox responds to user click interactions, such as toggling its checked state or triggering related events.

Allowed Values

  • "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 once when pressed and again when released.

Default value

"release"

Examples

Markup and runtime examples for clickMode:

HTML:

<smart-check-box click-mode="press"></smart-check-box>

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

const el = document.querySelector('smart-check-box');
el.clickMode = "pressAndRelease";

Read the current value:

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

disabledDetermines whether the checkbox is interactive or not. When set to true, the checkbox is enabled and the user can select or deselect it. When set to false, the checkbox is disabled, preventing any user interaction.boolean

Determines whether the checkbox is interactive or not. When set to true, the checkbox is enabled and the user can select or deselect it. When set to false, the checkbox is disabled, preventing any user interaction.

Default value

false

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-check-box disabled></smart-check-box>

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

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

Read the current value:

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

innerHTMLSets or retrieves the HTML markup contained within the element. When set, it updates the element’s contents by parsing the specified HTML string and replacing any existing child nodes. When accessed, it returns a string representing the element’s current HTML content.string

Sets or retrieves the HTML markup contained within the element. When set, it updates the element’s contents by parsing the specified HTML string and replacing any existing child nodes. When accessed, it returns a string representing the element’s current HTML content.

Default value

""""

Examples

Markup and runtime examples for innerHTML:

HTML:

<smart-check-box inner-h-t-m-l="Checkbox Label"></smart-check-box>

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

const el = document.querySelector('smart-check-box');
el.innerHTML = "Checkbox Label";

Read the current value:

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

localeSets or retrieves the current language code (e.g., 'en', 'fr') used for localization. This property works together with the messages property to select and display the appropriate set of localized messages based on the specified language.string

Sets or retrieves the current language code (e.g., 'en', 'fr') used for localization. This property works together with the messages property to select and display the appropriate set of localized messages based on the specified language.

Default value

"en"

Examples

Markup and runtime examples for locale:

HTML:

<smart-check-box locale="de"></smart-check-box>

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

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

Read the current value:

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

localizeFormatFunctionA callback function that allows you to define a custom formatting logic for messages returned by the Localization Module. Use this to adjust message content, structure, or variables before the final output is presented to the user.function | null

A callback function that allows you to define a custom formatting logic for messages returned by the Localization Module. Use this to adjust message content, structure, or variables before the final output is presented to the user.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

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

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

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

Read the current value:

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

messagesDefines or retrieves an object containing localized strings used throughout the widget’s interface. This property allows you to customize the text displayed by the widget for different languages or regions. It works in conjunction with the locale property, which determines the current language, ensuring that the appropriate set of strings is applied based on the selected locale.object

Defines or retrieves an object containing localized strings used throughout the widget’s interface. This property allows you to customize the text displayed by the widget for different languages or regions. It works in conjunction with the locale property, which determines the current language, ensuring that the appropriate set of strings is applied based on the selected locale.

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

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

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

nameSets or retrieves the value of the element’s name attribute. The name attribute identifies form elements when submitting HTML forms, allowing their values to be sent to the server as key-value pairs. This is essential for server-side processing of form data.string

Sets or retrieves the value of the element’s name attribute. The name attribute identifies form elements when submitting HTML forms, allowing their values to be sent to the server as key-value pairs. This is essential for server-side processing of form data.

Default value

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

Examples

Markup and runtime examples for name:

HTML:

<smart-check-box name="Name"></smart-check-box>

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

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

Read the current value:

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

readonlyWhen the element is set to readonly, users can view its content but are unable to modify or edit it. However, the element may still receive focus and allow text selection or copying, depending on the element's type and browser behavior. User interaction that changes the value or state of the element is disabled.boolean

When the element is set to readonly, users can view its content but are unable to modify or edit it. However, the element may still receive focus and allow text selection or copying, depending on the element's type and browser behavior. User interaction that changes the value or state of the element is disabled.

Default value

false

Examples

Markup and runtime examples for readonly:

HTML attribute:

<smart-check-box readonly></smart-check-box>

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

const el = document.querySelector('smart-check-box');
el.readonly = true;

Read the current value:

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

rightToLeftGets or sets a value that determines whether the element’s layout is aligned to support right-to-left (RTL) languages, such as Arabic or Hebrew, ensuring proper text direction and alignment for users in those locales.boolean

Gets or sets a value that determines whether the element’s layout is aligned to support right-to-left (RTL) languages, such as Arabic or Hebrew, ensuring proper text direction and alignment for users in those locales.

Default value

false
Try a demo showcasing the rightToLeft property.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

<smart-check-box right-to-left></smart-check-box>

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

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

Read the current value:

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

themeSpecifies the theme to be applied to the element. The selected theme controls the element’s visual appearance, including colors, fonts, and overall style, ensuring a consistent and cohesive look throughout the interface.string

Specifies the theme to be applied to the element. The selected theme controls the element’s visual appearance, including colors, fonts, and overall style, ensuring a consistent and cohesive look throughout the interface.

Default value

""

Examples

Markup and runtime examples for theme:

HTML:

<smart-check-box theme="blue"></smart-check-box>

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

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

Read the current value:

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

unfocusableWhen set to true, the element is rendered non-focusable, meaning it cannot receive keyboard or programmatic focus. This prevents users from navigating to the element using the keyboard (e.g., with the Tab key) or through scripts.boolean

When set to true, the element is rendered non-focusable, meaning it cannot receive keyboard or programmatic focus. This prevents users from navigating to the element using the keyboard (e.g., with the Tab key) or through scripts.

Default value

false

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

<smart-check-box unfocusable></smart-check-box>

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

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

Read the current value:

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

unlockKeySpecifies or retrieves the unlockKey used to activate or grant access to the product. This key serves as a security credential required to unlock and use the product’s features.string

Specifies or retrieves the unlockKey used to activate or grant access to the product. This key serves as a security credential required to unlock and use the product’s features.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

<smart-check-box unlock-key=""></smart-check-box>

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

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

Read the current value:

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

valueRetrieves the current value of the element or assigns a new value to it. This property allows you to programmatically read or update the element’s value—for example, reading user input from a form field or setting a default value dynamically.string

Retrieves the current value of the element or assigns a new value to it. This property allows you to programmatically read or update the element’s value—for example, reading user input from a form field or setting a default value dynamically.

Default value

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

Examples

Markup and runtime examples for value:

HTML:

<smart-check-box value="Value"></smart-check-box>

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

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

Read the current value:

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

Events

changeThis event is triggered whenever the widget's checked state changes, such as when the user selects or deselects (checks or unchecks) the widget. It allows you to respond dynamically whenever the widget transitions between checked and unchecked states.CustomEvent

This event is triggered whenever the widget's checked state changes, such as when the user selects or deselects (checks or unchecks) the widget. It allows you to respond dynamically whenever the widget transitions between checked and unchecked states.

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

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-check-box')?.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's checked state changes from unchecked to checked, such as when a user selects or activates the widget. It allows you to execute custom logic in response to the widget being checked.CustomEvent

This event is triggered whenever the widget's checked state changes from unchecked to checked, such as when a user selects or activates the widget. It allows you to execute custom logic in response to the widget being checked.

  • 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-check-box')?.addEventListener('checkValue', (event) => {
    const detail = event.detail,
        changeType = detail.changeType;

	// event handling code goes here.
})

uncheckValueThis event is triggered whenever the widget transitions from a checked (selected) state to an unchecked (deselected) state, indicating that the user has cleared or deselected the widget (e.g., by unchecking a checkbox or turning off a toggle switch).CustomEvent

This event is triggered whenever the widget transitions from a checked (selected) state to an unchecked (deselected) state, indicating that the user has cleared or deselected the widget (e.g., by unchecking a checkbox or turning off a toggle switch).

  • 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-check-box')?.addEventListener('uncheckValue', (event) => {
    const detail = event.detail,
        changeType = detail.changeType;

	// event handling code goes here.
})

CSS Variables

--smart-check-box-default-sizevar()

Default value

"calc(1px + 1/2 * var(--smart-editor-height))"

Default size for the check box used in smartCheckBox and smartListItem.