Radio Button

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

None

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

None

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

None

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
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
Combining the checked and disabled states

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:

  1. Assign a unique id to each instance of AlexaRadioButton in the group.
  2. 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"
         }
       ]
     }
    
  3. 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.

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.

Examples of AlexaRadioButton with different colors and sizes
Examples of AlexaRadioButton with different colors and sizes