RadioButton — Smart UI JavaScript API

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

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

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

      el.checked = true;
      el.innerHTML = 'Standard shipping';

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

Developer Quick Reference

Component: RadioButton   Framework: JavaScript   Selector: smart-radio-button

API counts: 17 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.radiobutton.js

The Radio Button component lets you add a radio button and assign it to a radio group. Users can select only one radio button at a time within a radio group

Class

RadioButton

RadioButton

The Radio Button component lets you add a radio button and assign it to a radio group. Users can select only one radio button at a time within a radio group

Selector

smart-radio-button

Quick picks

changedisabledvalue

Properties

AanimationSets or retrieves the current animation mode. When this property is set to 'none', all animations are disabled for the associated element. Use this property to enable, disable, or adjust the animation behavior as needed.
CcheckedSets or retrieves the current checked state of the control. This property allows you to specify whether the control is checked, unchecked, or—if supported—set to an indeterminate state. You can use it to update the visual state of elements like checkboxes or radio buttons, or to query their current status in your application logic.
CcheckModeSets or retrieves the specific part of the element responsible for toggling its state (such as showing or hiding content). This attribute identifies which internal component or sub-element responds to toggle actions, enabling interactive behavior.
CclickModeSpecifies how the radio button responds to user click events, determining whether the button is selected, toggled, or triggers a specific action when clicked.
DdisabledControls whether the ratio button is displayed and functional. When enabled, users can interact with the ratio button; when disabled, the button is hidden or inactive.
GgroupNameSets or retrieves the name of the group to which the widget belongs. This property allows you to organize multiple widgets into logical groups, enabling group-based behavior or styling. When setting this property, the widget is associated with the specified group; when getting, it returns the current group name assigned to the widget.
IinnerHTMLGets or sets the HTML content contained within the widget. Setting this property updates the widget’s inner HTML structure, while getting it returns the current HTML markup inside the widget. Use this property to dynamically modify or retrieve the widget’s content.
LlocaleSets or retrieves the current language code (e.g., "en", "fr", "es") used by the component or application. This property works together with the messages property to determine which set of localized messages or translations should be displayed to the user. Adjusting the language value dynamically updates the displayed content based on the corresponding messages for the selected language.
LlocalizeFormatFunctionCallback function associated with the localization module, typically invoked to handle events or updates related to language changes, text translation, or region-specific content within the application.
MmessagesDefines an object that maps different password strength states to their corresponding descriptive string values. This allows you to customize the messages shown to users based on the evaluated strength of their password (e.g., "weak," "medium," "strong").
NnameGets the current name of the widget or assigns a new name to the widget. The name serves as a unique identifier, which can be used for tracking, referencing, or interacting with the widget programmatically.
RreadonlyWhen the custom element is set to readonly, its value cannot be modified by user input or interaction. All form controls within the element will display their current values but will be non-editable, preventing users from changing, adding, or deleting content. However, the element may still support programmatic updates via JavaScript.
RrightToLeftSpecifies or retrieves a Boolean value that determines whether the element’s content is aligned to accommodate right-to-left (RTL) languages, such as Arabic or Hebrew. When set to true, the element’s layout and text flow are adjusted to support RTL locales and fonts.
TthemeSpecifies the visual theme to be applied. The selected theme controls the overall appearance, including colors, fonts, and styling of the element.
UunfocusableWhen set to true, this property prevents the element from receiving keyboard focus, making it impossible for users to navigate to the element using the Tab key or other focus methods.
UunlockKeyDefines or retrieves the unlockKey property, which serves as the credential required to unlock access to the product.
VvalueSets a new value for the widget or retrieves its current value, depending on the context in which the method is called. This allows you to programmatically update the widget's content or access the value entered or selected by the user.

Events

CchangeThis event is triggered whenever the widget’s checked state changes, such as when a user selects (checks) or deselects (unchecks) the widget. It allows you to execute custom logic in response to the user interacting with the widget’s selection control.
CcheckValueThis event is triggered whenever the widget's checked state changes from unchecked to checked, indicating that the user has selected or activated the widget. This event is typically used to execute custom logic in response to the widget being checked, such as updating the UI, submitting data, or enabling related features.
UuncheckValueThis event is triggered whenever the user deselects or unchecks the widget, indicating a change in its state from checked to unchecked. It allows developers to respond to the action of unchecking, such as updating the user interface or processing form data.

Properties

animationSets or retrieves the current animation mode. When this property is set to 'none', all animations are disabled for the associated element. Use this property to enable, disable, or adjust the animation behavior as needed."none" | "simple" | "advanced"

Sets or retrieves the current animation mode. When this property is set to 'none', all animations are disabled for the associated element. Use this property to enable, disable, or adjust the animation behavior as needed.

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

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

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

Read the current value:

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

checkedSets or retrieves the current checked state of the control. This property allows you to specify whether the control is checked, unchecked, or—if supported—set to an indeterminate state. You can use it to update the visual state of elements like checkboxes or radio buttons, or to query their current status in your application logic.boolean

Sets or retrieves the current checked state of the control. This property allows you to specify whether the control is checked, unchecked, or—if supported—set to an indeterminate state. You can use it to update the visual state of elements like checkboxes or radio buttons, or to query their current status in your application logic.

Default value

false

Examples

Markup and runtime examples for checked:

HTML attribute:

<smart-radio-button checked></smart-radio-button>

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

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

Read the current value:

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

checkModeSets or retrieves the specific part of the element responsible for toggling its state (such as showing or hiding content). This attribute identifies which internal component or sub-element responds to toggle actions, enabling interactive behavior."both" | "input" | "label"

Sets or retrieves the specific part of the element responsible for toggling its state (such as showing or hiding content). This attribute identifies which internal component or sub-element responds to toggle actions, enabling interactive behavior.

Default value

"both"

Examples

Markup and runtime examples for checkMode:

HTML:

<smart-radio-button check-mode="input"></smart-radio-button>

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

const el = document.querySelector('smart-radio-button');
el.checkMode = "label";

Read the current value:

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

clickModeSpecifies how the radio button responds to user click events, determining whether the button is selected, toggled, or triggers a specific action when clicked."hover" | "press" | "release" | "pressAndRelease"

Specifies how the radio button responds to user click events, determining whether the button is selected, toggled, or triggers a specific action when clicked.

Default value

"release"

Examples

Markup and runtime examples for clickMode:

HTML:

<smart-radio-button click-mode="press"></smart-radio-button>

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

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

Read the current value:

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

disabledControls whether the ratio button is displayed and functional. When enabled, users can interact with the ratio button; when disabled, the button is hidden or inactive.boolean

Controls whether the ratio button is displayed and functional. When enabled, users can interact with the ratio button; when disabled, the button is hidden or inactive.

Default value

false

Examples

Markup and runtime examples for disabled:

HTML attribute:

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

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

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

Read the current value:

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

groupNameSets or retrieves the name of the group to which the widget belongs. This property allows you to organize multiple widgets into logical groups, enabling group-based behavior or styling. When setting this property, the widget is associated with the specified group; when getting, it returns the current group name assigned to the widget.string

Sets or retrieves the name of the group to which the widget belongs. This property allows you to organize multiple widgets into logical groups, enabling group-based behavior or styling. When setting this property, the widget is associated with the specified group; when getting, it returns the current group name assigned to the widget.

Default value

""""

Examples

Markup and runtime examples for groupName:

HTML:

<smart-radio-button group-name="Group"></smart-radio-button>

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

const el = document.querySelector('smart-radio-button');
el.groupName = "New Group";

Read the current value:

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

innerHTMLGets or sets the HTML content contained within the widget. Setting this property updates the widget’s inner HTML structure, while getting it returns the current HTML markup inside the widget. Use this property to dynamically modify or retrieve the widget’s content.string

Gets or sets the HTML content contained within the widget. Setting this property updates the widget’s inner HTML structure, while getting it returns the current HTML markup inside the widget. Use this property to dynamically modify or retrieve the widget’s content.

Default value

""""

Examples

Markup and runtime examples for innerHTML:

HTML:

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

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

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

Read the current value:

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

localeSets or retrieves the current language code (e.g., "en", "fr", "es") used by the component or application. This property works together with the messages property to determine which set of localized messages or translations should be displayed to the user. Adjusting the language value dynamically updates the displayed content based on the corresponding messages for the selected language.string

Sets or retrieves the current language code (e.g., "en", "fr", "es") used by the component or application. This property works together with the messages property to determine which set of localized messages or translations should be displayed to the user. Adjusting the language value dynamically updates the displayed content based on the corresponding messages for the selected language.

Default value

"en"

Examples

Markup and runtime examples for locale:

HTML:

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

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

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

Read the current value:

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

localizeFormatFunctionCallback function associated with the localization module, typically invoked to handle events or updates related to language changes, text translation, or region-specific content within the application.function | null

Callback function associated with the localization module, typically invoked to handle events or updates related to language changes, text translation, or region-specific content within the application.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

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

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

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

Read the current value:

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

messagesDefines an object that maps different password strength states to their corresponding descriptive string values. This allows you to customize the messages shown to users based on the evaluated strength of their password (e.g., "weak," "medium," "strong").object

Defines an object that maps different password strength states to their corresponding descriptive string values. This allows you to customize the messages shown to users based on the evaluated strength of their password (e.g., "weak," "medium," "strong").

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

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

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

nameGets the current name of the widget or assigns a new name to the widget. The name serves as a unique identifier, which can be used for tracking, referencing, or interacting with the widget programmatically.string

Gets the current name of the widget or assigns a new name to the widget. The name serves as a unique identifier, which can be used for tracking, referencing, or interacting with the widget programmatically.

Default value

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

Examples

Markup and runtime examples for name:

HTML:

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

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

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

Read the current value:

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

readonlyWhen the custom element is set to readonly, its value cannot be modified by user input or interaction. All form controls within the element will display their current values but will be non-editable, preventing users from changing, adding, or deleting content. However, the element may still support programmatic updates via JavaScript.boolean

When the custom element is set to readonly, its value cannot be modified by user input or interaction. All form controls within the element will display their current values but will be non-editable, preventing users from changing, adding, or deleting content. However, the element may still support programmatic updates via JavaScript.

Default value

false

Examples

Markup and runtime examples for readonly:

HTML attribute:

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

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

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

Read the current value:

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

rightToLeftSpecifies or retrieves a Boolean value that determines whether the element’s content is aligned to accommodate right-to-left (RTL) languages, such as Arabic or Hebrew. When set to true, the element’s layout and text flow are adjusted to support RTL locales and fonts.boolean

Specifies or retrieves a Boolean value that determines whether the element’s content is aligned to accommodate right-to-left (RTL) languages, such as Arabic or Hebrew. When set to true, the element’s layout and text flow are adjusted to support RTL locales and fonts.

Default value

false
Try a demo showcasing the rightToLeft property.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

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

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

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

Read the current value:

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

themeSpecifies the visual theme to be applied. The selected theme controls the overall appearance, including colors, fonts, and styling of the element.string

Specifies the visual theme to be applied. The selected theme controls the overall appearance, including colors, fonts, and styling of the element.

Default value

""

Examples

Markup and runtime examples for theme:

HTML:

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

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

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

Read the current value:

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

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

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

Default value

false

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

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

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

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

Read the current value:

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

unlockKeyDefines or retrieves the unlockKey property, which serves as the credential required to unlock access to the product.string

Defines or retrieves the unlockKey property, which serves as the credential required to unlock access to the product.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

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

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

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

Read the current value:

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

valueSets a new value for the widget or retrieves its current value, depending on the context in which the method is called. This allows you to programmatically update the widget's content or access the value entered or selected by the user.string

Sets a new value for the widget or retrieves its current value, depending on the context in which the method is called. This allows you to programmatically update the widget's content or access the value entered or selected by the user.

Default value

""""

Examples

Markup and runtime examples for value:

HTML:

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

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

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

Read the current value:

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

Events

changeThis event is triggered whenever the widget’s checked state changes, such as when a user selects (checks) or deselects (unchecks) the widget. It allows you to execute custom logic in response to the user interacting with the widget’s selection control.CustomEvent

This event is triggered whenever the widget’s checked state changes, such as when a user selects (checks) or deselects (unchecks) the widget. It allows you to execute custom logic in response to the user interacting with the widget’s selection control.

  • 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-radio-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's checked state changes from unchecked to checked, indicating that the user has selected or activated the widget. This event is typically used to execute custom logic in response to the widget being checked, such as updating the UI, submitting data, or enabling related features.CustomEvent

This event is triggered whenever the widget's checked state changes from unchecked to checked, indicating that the user has selected or activated the widget. This event is typically used to execute custom logic in response to the widget being checked, such as updating the UI, submitting data, or enabling related features.

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

	// event handling code goes here.
})

uncheckValueThis event is triggered whenever the user deselects or unchecks the widget, indicating a change in its state from checked to unchecked. It allows developers to respond to the action of unchecking, such as updating the user interface or processing form data.CustomEvent

This event is triggered whenever the user deselects or unchecks the widget, indicating a change in its state from checked to unchecked. It allows developers to respond to the action of unchecking, such as updating the user interface or processing form data.

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

	// event handling code goes here.
})

CSS Variables

--smart-radio-button-default-sizevar()

Default value

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

Default size for the radio button.