Button

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

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.

Compatibility

AlexaButton 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 AlexaButton on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

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	Widget support	Version added
`accessibilityLabel`	String	`buttonText`	A string describing the button. Voice over reads this string when the user selects the button.	Not supported	1.1.0
`buttonIconName`	String	—	The name of an icon from the `alexa-icon` package to display on the button. For a list of valid icon names, see Alexa Icon Library Reference. Don't set both `buttonIconSource` and `buttonIconName`. When both properties are set, no icon displays on the button.	Not supported	1.6.0
`buttonIconSource`	String	—	The name of a custom AVG icon to display on the button. The specified AVG must be defined in the document or in an imported package. Don't set both `buttonIconSource` and `buttonIconName`. When both properties are set, no icon displays on the button.	Not supported	1.6.0
`buttonIconStyle`	String	—	Applies when `buttonIconSource` contains a value. Specifies a vector graphic style to pass to the custom icon source.	Not supported	1.6.0
`buttonStyle`	String	`contained`	The style of the button. Set to one of the following: `contained`, `outlined`, `ingress`, `egress`, or `borderless`. For details about which styles to use, see Button appearance. The `theme` determines the button colors.	Not supported	1.2.0
`buttonText`	String	—	The text displayed on the button. This text should indicate the purpose of the button.	Not supported	1.1.0
`entities`	Array	—	Array of entity data to bind to this component.	Not supported	1.2.0
`lang`	String	`${environment.lang}`	The language for the text displayed in the button. This language determines the default font and formatting used for the text displayed on the button. For example, when set to `ar-SA`, the component uses Arabic fonts when available on the device, and also uses different formatting to differentiate between touch-forward and voice-forward styles. Set to a BCP-47 string. For more details about language-specific fonts for responsive components, see Language-specific fonts in the components and templates.	Not supported	1.4.0
`layoutDirection`	String	`inherit`	Specifies the layout direction for the button. Set this property to either `LTR` (left-to-right) or `RTL` (right-to-left). When not set, this property inherits the `layoutDirection` specified in the parent component. For more details about support for right-to-left languages in the responsive components, see Support for Right-to-left Languages.	Not supported	1.4.0
`primaryAction`	Command	—	The action to trigger when the user selects the button.	Not supported	1.1.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	Not supported	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.	Not supported	1.2.0
`type`	String	—	Always set to `AlexaButton`	Not supported	1.1.0

Accessibility

The AlexaButton component is a touchable component configured as a 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 activate the button.

The screen reader reads the accessibilityLabel string to describe the AlexaButton component. The accessibilityLabel defaults to the value of the buttonText property. If you leave buttonText not set to create an icon-only button, make sure you set the accessibilityLabel property to a string that describes the purpose of the button.

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

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.

buttonStyle

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.
borderless – In the normal state, this style displays the button with no surrounding shape or color. The button shape appears for the pressed and focused states.

touchForward

Use the touchForward option 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. Make sure your interaction model lets users select the buttons by voice.
- The button displays the text in the voice-enabled style to signify that the user can speak to trigger the button in addition to using touch.
- The default voice-enabled style displays the text in an italic font.
- Some language-specific fonts don't support italic text. The button text displays in plain text for these languages. Set the lang property to a language or locale string to use language-specific fonts. For example, when the lang property is ar or ar-SA (Arabic), the button text displays in plain text instead of italics. (APL 1.7 and alexa-layouts 1.4.0 or later).
Set touchForward to true when you expect users to interact with the button primarily with touch instead of speech.
- The button displays the text in the touch-forward style to signify that the buttons aren't "speakable".
- The default touch-forward style displays text in plain text instead of italics.
- For languages that don't support italics, the button automatically encloses the button text in quotation marks to distinguish the style from the voice-enabled style. For example, when the lang property is ar or ar-SA (Arabic), the button encloses the button text in quotation marks. (APL 1.7 and alexa-layouts 1.4.0 or later).

For examples of the buttonStyle and touchForward options, see AlexaButton examples.

Button icons

An AlexaButton can display an icon. The icon to display must be an Alexa Vector Graphic (AVG). You can use an icon from an Amazon-provided library of icons, or provide your own.

Note: To display an icon on AlexaButton, you must use alexa-layouts 1.6.0 or later.

When you provide both the icon and the buttonText, the icon displays before the text. When you provide the icon and no buttonText, the button shrinks and displays the icon instead of text. When you don't provide buttonText, make sure you set the accessibilityLabel property to a string that describes the purpose of the button.

Use an icon from the icon library

The Alexa icon package (alexa-icon) provides a set of icons defined in AVG format. For the list of available icons, see Alexa Icon Library Reference. To display an icon from the library, you must import the package, then set the buttonIconName to the name of the icon.

To display an icon from icon library

Import both the alexa-icon and alexa-layouts packages.

 {
   "import": [
     {
       "name": "alexa-layouts",
       "version": "1.7.0"
     },
     {
       "name": "alexa-icon",
       "version": "1.0.0"
     }
   ]
 }

Add AlexaButton to the document and set the buttonIconName to the name of the icon. Provide the name exactly as it is shown in Alexa Icon Library Reference.
```
 {
   "type": "AlexaButton",
   "buttonText": "This button has a calendar icon",
   "buttonIconName": "ic_calendar"
 }
```

The following example shows two rows of buttons, one with the buttonText and buttonIconName, and one with just buttonIconName. The second row sets accessibilityLabel on the AlexaButton component. For both examples, the icon names and button text is in the data source.

Use a custom icon

To display a custom icon, set the buttonIconSource property to the name of an AVG to display. You can define your graphic in the document, or in an external package.

The following example shows two examples of AlexaButton with a custom icon.

AlexaButton examples

The following example displays the five options in buttonStyle and the two settings for touchForward. When the user selects the button, the button runs the SetValue command to update a message in a Text component.

The following example displays the same five button styles with lang set to ar-sa and layoutDirection set to RTL.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023