Button (1.2.0 - 1.3.0)

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

(This is not the most recent version of AlexaButton. Use the Other Versions option to see the documentation for the most recent version of AlexaButton)

The Alexa button responsive component (AlexaButton) displays a button the user can select with touch or a controller. You can configure the text displayed on the button, the button appearance, and the command to run when the user selects the button.

Import the alexa-layouts package

To use AlexaButton, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaButton was introduced in version 1.1.0.

AlexaButton Parameters

All parameters except type are optional.

Name	Type	Default	Description	Version added/updated
`accessibilityLabel`	String	—	A string describing the button. Voice over reads this string when the user selects the button.	1.1.0
`buttonStyle`	String	`contained`	The style of the button. Set to `contained`, `outlined`, `ingress`, or `egress`. For details about which styles to use, see Button appearance. The `theme` determines the button colors.	1.2.0
`buttonText`	String	`buttonText`	The text displayed on the button. This text should indicate the purpose of the button.	1.1.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 button.	1.1.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	1.1.0
`touchForward`	Boolean	`false`	When `true`, use the 'touch-forward' text style for the button text. This style displays the button text without italics. When `false`, assume the user is interacting with the button by voice and use the default 'voice-enabled' text style. For details about styling `AlexaButton` see Button appearance.	1.2.0
`type`	String	—	Always set to `AlexaButton`	1.1.0

Button appearance

Use the buttonStyle and touchForward properties to configure the look of the button. The provided styles format the button consistently with overall Alexa visual design.

To set the button style, set the buttonStyle property to one of the following values:

contained – Use this style for the main action you want the user to take. This style displays a button filled in with a semi-transparent background color.
outlined – Use this style for secondary actions. This style displays a button outlined in a solid color, but with a transparent body.
ingress – Use this style for actions such as "confirm", "yes", and "next". This style uses solid colors like contained, but with a different color scheme.
egress – Use this style for actions such as "decline", "no", and "previous". This style uses an outline with a transparent body.

Use the touchForward toggle to set the font style for the button according to how you expect users to interact with the button:

Set touchForward to false when you expect users to interact with the button with voice. This setting is the default. The button displays the buttonText in an italic font to signify that the user can speak to trigger the button in addition to using touch. Make sure your interaction model lets users select the buttons by voice.
Set touchForward to true when you expect users to interact with the button primarily with touch. The button displays the buttonText in a plain font to signify that the buttons are not "speakable".

The four button styles in voice-forward and touch-forward variants

AlexaButton example

The following example shows a button that uses the default contained and voice-forward settings. When the user selects the button, the button runs the SendEvent command to send a UserEvent to the skill.

{
  "type": "AlexaButton",
  "buttonText": "Button with default settings",
  "id": "idForThisButton",
  "primaryAction": {
    "type": "SendEvent",
    "arguments": [
      "AlexaButton"
    ]
  }
}

This following example shows a complete document and data source that displays the four options in buttonStyle and the two settings for touchForward.

Copied to clipboard.

To learn how to test APL examples in the authoring tool, see Experiment with APL Examples in the Authoring Tool.

{
  "type": "APL",
  "version": "2024.2",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "layouts": {
    "ButtonRow": {
      "parameters": [
        "buttons",
        "touchForwardSetting",
        "exampleType"
      ],
      "item": {
        "type": "Sequence",
        "width": "100%",
        "scrollDirection": "horizontal",
        "alignSelf": "center",
        "data": "${buttons}",
        "items": [
          {
            "type": "AlexaButton",
            "buttonText": "${data.buttonText}",
            "id": "${data.id}_${exampleType}",
            "buttonStyle": "${data.buttonStyle}",
            "touchForward": "${touchForwardSetting}",
            "primaryAction": {
              "type": "SendEvent",
              "arguments": [
                "AlexaButton"
              ]
            }
          }
        ]
      }
    }
  },
  "mainTemplate": {
    "parameters": [
      "buttonExampleData"
    ],
    "items": [
      {
        "type": "Container",
        "height": "100vh",
        "width": "100vw",
        "paddingLeft": "@marginHorizontal",
        "paddingRight": "@marginHorizontal",
        "justifyContent": "center",
        "items": [
          {
            "type": "Text",
            "text": "${buttonExampleData.voiceHeading}"
          },
          {
            "type": "ButtonRow",
            "touchForwardSetting": false,
            "buttons": "${buttonExampleData.buttons}",
            "exampleType": "VoiceForward",
            "spacing": "@spacingMedium"
          },
          {
            "type": "AlexaDivider",
            "spacing": "@spacingMedium"
          },
          {
            "type": "Text",
            "text": "${buttonExampleData.touchHeading}",
            "spacing": "@spacingMedium"
          },
          {
            "type": "ButtonRow",
            "touchForwardSetting": true,
            "buttons": "${buttonExampleData.buttons}",
            "exampleType": "TouchForward",
            "spacing": "@spacingMedium"
          }
        ]
      }
    ]
  }
}

For an image that shows the results of this document, see Button appearance, earlier.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023