CheckBox JAVASCRIPT UI Component API

CheckBox Javascript API

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

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

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

Example

Set the animation property. 

 <smart-check-box animation='none'></smart-check-box>

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

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

Get the animation property. 

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

checkedboolean

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.

Example

Set the checked property. 

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

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

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

Get the checked property. 

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

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

Example

Set the checkMode property. 

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

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

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

Get the checkMode property. 

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

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

Example

Set the clickMode property. 

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

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

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

Get the clickMode property. 

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

disabledboolean

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

Example

Set the disabled property. 

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

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

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

Get the disabled property. 

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

innerHTMLstring

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

""""

Example

Set the innerHTML property. 

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

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

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

Get the innerHTML property. 

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

unlockKeystring

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

""

Example

Set the unlockKey property. 

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

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

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

Get the unlockKey property. 

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

localestring

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"

Example

Set the locale property. 

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

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

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

Get the locale property. 

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

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

Example

Set the localizeFormatFunction property. 

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

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

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

Get the localizeFormatFunction property. 

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

messagesobject

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

}

Example

Set the messages property. 

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

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

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

namestring

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

""""

Example

Set the name property. 

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

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

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

Get the name property. 

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

readonlyboolean

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

Example

Set the readonly property. 

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

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

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

Get the readonly property. 

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

rightToLeftboolean

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.

Example

Set the rightToLeft property. 

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

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

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

Get the rightToLeft property. 

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

unfocusableboolean

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

Example

Set the unfocusable property. 

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

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

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

Get the unfocusable property. 

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

themestring

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

""

Example

Set the theme property. 

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

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

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

Get the theme property. 

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

valuestring

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.

Example

Set the value property. 

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

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

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

Get the value property. 

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

Events

changeCustomEvent

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.

Example

Set up the event handler of change event. 

const checkbox = document.querySelector('smart-check-box');
checkbox.addEventListener('change', function (event) {
    const detail = event.detail,
        value = detail.value,
        oldValue = detail.oldValue,
        changeType = detail.changeType;

	// event handling code goes here.
})

checkValueCustomEvent

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.

Example

Set up the event handler of checkValue event. 

const checkbox = document.querySelector('smart-check-box');
checkbox.addEventListener('checkValue', function (event) {
    const detail = event.detail,
        changeType = detail.changeType;

	// event handling code goes here.
})

uncheckValueCustomEvent

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.

Example

Set up the event handler of uncheckValue event. 

const checkbox = document.querySelector('smart-check-box');
checkbox.addEventListener('uncheckValue', function (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.