Button

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

None

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

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 differntiate between touch-forward and voice-forward styles. Set to a BCP-47 string.

For more about langauge-specific fonts for responsive components, see Language-specific fonts in the components and templates.

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 about support for right-to-left languages in the responsive components, see Support for Right-to-left Languages.

1.4.0

primaryAction

Command

None

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

None

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.

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.

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).
The four button styles in voice-forward and touch-forward variants
The four button styles in voice-forward and touch-forward variants
The four button styles in voice-forward and touch-forward variants in a font without italics
The four button styles in voice-forward and touch-forward variants in a font without italics

For design guidance for AlexaButton, see Button.

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.

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