Radio Button

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

The Alexa switch responsive component (AlexaRadioButton) displays a radio button the user can toggle on and off. You can control the button size, colors, and commands to run when the user interacts with the button.

Compatibility

AlexaRadioButton is designed to work with all standard viewport profiles in the alexa-viewport-profiles package:

All hub round profiles
All hub landscape profiles
All hub portrait profiles
All mobile profiles
All TV profiles

If you use AlexaRadioButton on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Import the alexa-layouts package

To use AlexaRadioButton, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaRadioButton was introduced in version 1.2.0.

AlexaRadioButton Parameters

All parameters except type are optional.

Name	Type	Default	Description	Widget support	Version added
`accessibilityLabel`	String	—	A string describing the radio button. Voice over reads this string when the user selects the button.	Not supported	1.2.0
`entities`	Array	—	Array of entity data to bind to this component.	Not supported	1.2.0
`primaryAction`	Command	—	The action to trigger when the user selects the radio button.	Not supported	1.2.0
`radioButtonColor`	Color	A blue color. The specific shade depends on the specified `theme`.	Fill color to use for the radio button when it's selected (`checked` is `true`).	Not supported	1.2.0
`radioButtonHeight`	Dimension	Height based on the viewport	Height of the radio button	Not supported	1.2.0
`radioButtonWidth`	Dimension	Width based on the viewport	Width of the radio button	Not supported	1.2.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	Not supported	1.2.0
`type`	String	—	Always set to `AlexaRadioButton`	Not supported	1.2.0

checked state

AlexaRadioButton uses the standard checked component state to determine whether to show the component in the selected or not selected state. When you place the component in your document, initialize checked to true or false:

Set checked to true to show the radio button in the selected state. This displays a circle filled with a solid color and a black dot in the middle.
Set to false to display the radio button in the not selected state. This displays the outline of a circle. The component sets checked to false by default.

When the user interacts with the button, the component automatically toggles checked state. You don't need to track or update the checked state yourself.

The following example displays four radio buttons in two rows. In the first row, the buttons initialize checked to true. In the second row, they leave checked set to the default false.

Examples of the radio button with the checked state on and off

disabled state

AlexaRadioButton uses the standard disabled component state to determine whether to show the component enabled or disabled. When disabled is true, the radio button doesn't respond to any user interactions such as touch or a remote.

The disabled state is independent of checked, so you can display the disabled radio button as selected or not selected.

The following example displays four disabled radio buttons in two rows. In the first row, the radio buttons set checked to true. In the second row, they leave checked set to the default false.

Combining the checked and disabled states

Accessibility

The AlexaRadioButton component is a touchable component configured as a radio button. On a device with the VoiceView screen reader enabled, the user can tap the component to select it, then double-tap on the screen to select or clear the button.

For details about accessibility and APL, see APL Accessibility Guide.

Manage the state for a radio button group

Each radio button you add to your layout operates independently of other radio buttons and other components. There is no automatic grouping of multiple radio buttons on a layout.

If you need to group together multiple AlexaRadioButton components to present a set of mutually exclusive options, you must add the logic to connect the radio buttons yourself. You can use the primaryAction property on each AlexaRadioButton to run commands that change the checked state of the other buttons in the group to ensure that the user can't clear all the options or select more than one. Make sure your commands address the following scenarios:

User selects a new item – Set the checked property for the previous item to false to clear the previously selected radio button.
User selects the same item – Set the checked property for the current item to true. This is necessary because the default AlexaRadioButton behavior works as a toggle. Selecting the button when it is already selected clears the selection. Override this behavior by setting checked to true.

One approach for keeping track of the currently selected item and managing the state in a group is the following:

Assign a unique id to each instance of AlexaRadioButton in the group.

To keep track of the selected item, use the bind property to create a variable. Define this variable in the parent component that contains the radio buttons.

 {
   "bind": [
     {
       "name": "CurrentSelectedRadioButtonId",
       "value": "stringIDOfFirstButtonToSelect"
     }
   ]
 }

Define a set of commands that update the radio buttons and the bind property. Assign these commands to the primaryAction property of each AlexaRadioButton so that they run every time the user selects one of the buttons.

The following example shows a user-defined command that clears the previously selected radio button, then saves the id of the newly selected radio button to the bind property named CurrentSelectedRadioButtonId.

Copied to clipboard.

{
  "ManageRadioButtonGroupState": {
    "command": [
      {
        "when": "${event.source.id != CurrentSelectedRadioButtonId}",
        "type": "Sequential",
        "description": "User selected a different radio button.",
        "commands": [
          {
            "type": "SetValue",
            "description": "Set the checked property for the previously selected item to false.",
            "componentId": "${CurrentSelectedRadioButtonId}",
            "property": "checked",
            "value": false
          },
          {
            "type": "SetValue",
            "description": "Save the ID of the new item into a bound variable called CurrentSelectedRadioButtonId.",
            "property": "CurrentSelectedRadioButtonId",
            "value": "${event.source.id}"
          }
        ]
      },
      {
        "when": "${event.source.id == CurrentSelectedRadioButtonId}",
        "description": "User selected the same option. Override normal AlexaRadioButton behavior and reselect this item.",
        "type": "SetValue",
        "property": "checked",
        "value": true
      }
    ]
  }
}

The following example shows a full APL document and data source that uses a Sequence to present a list of radio buttons. The IDs and text for the radio buttons are provided in an array in the data source. The example includes a layout called RadioButtonRow to place an AlexaRadioButton alongside descriptive text. A Send button at the bottom of the screen sends a UserEvent to the skill with the ID of the selected option. Test this example with a skill to test the user event.

AlexaRadioButton examples

The following example shows a complete document that displays multiple radio buttons with different colors and sizes. The radio buttons are provided in a data source. Each row shows the same radio button in the dark and light themes. When you select a radio button, the radio button runs a user-defined command that updates the header subtitle with information about the selected radio button. The command gets the current checked state for the AlexaCheckbox from the event.source.checked property.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023