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.

Import the alexa-layouts package

To use AlexaRadioButton, import the alexa-layouts package.

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

AlexaRadioButton Parameters

All parameters except type are optional.

Name	Type	Default	Description	Version added/updated
`accessibilityLabel`	String	—	A string describing the radio button. Voice over reads this string when the user selects the button.	1.2.0
`entities`	Array	—	Array of entity data to bind to this component.	1.2.0
`primaryAction`	Command	—	The action to trigger when the user selects the radio button.	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`).	1.2.0
`radioButtonHeight`	Dimension	Height based on the viewport	Height of the radio button	1.2.0
`radioButtonWidth`	Dimension	Width based on the viewport	Width of the radio button	1.2.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	1.2.0
`type`	String	—	Always set to `AlexaRadioButton`	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.

Last updated: Mar 02, 2023