Icon Button

The Alexa icon button responsive component (AlexaIconButton) displays a vector graphic as a button. The user can select the button with touch or a controller. You specify the graphic to display, the button style, and the command to run when the user selects the button. AlexaIconButton automatically handles different states, such as disabled, pressed, and focused.

Compatibility

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

Import the alexa-layouts package

To use AlexaIconButton, import the alexa-layouts package.

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

AlexaIconButton Parameters

All parameters except type are optional.

Name Type Default Description Widget support Version added

accessibilityLabel

String

icon

A string describing the button. Voice over reads this string when the user selects the button.

Not supported

1.1.0

buttonId

String

Unique identifier for the AlexaIconButton.

Not supported

1.2.0

buttonSize

Dimension

72dp

Size (height and width) of the icon button.

Not supported

1.1.0

buttonStyle

String

image

One of image or contained. When image, the button displays the provided vector graphic as is. When contained, the button displays the icon over a filled circle.

Not supported

1.1.0

entities

Array

—

Array of entity data to bind to this component.

Not supported

1.2.0

primaryAction

Command

—

The command 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

type

String

—

Always set to AlexaIconButton.

Not supported

1.1.0

vectorSource

String

—

The AVG path drawing data. This is the same value you would include in the pathData property of an Alexa Vector Graphic. The graphic must fit into a 24dp x 24dp box. For details about defining the path data for a vector graphic, see pathData.

Not supported

1.1.0

Accessibility

The AlexaIconButton 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 string "icon." Set this property to a value that explains what the button does.

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

AlexaIconButton example

This example displays a "home" icon button with the default image style.

{
  "type": "AlexaIconButton",
  "buttonSize": "72dp",
  "vectorSource": "M21.343,8.661l-7.895-7.105c-0.823-0.741-2.073-0.741-2.896,0L2.657,8.661C2.238,9.039,2,9.564,2,10.113V20c0,1.105,0.943,2,2.105,2H9v-9h6v9h4.895C21.057,22,22,21.105,22,20v-9.887C22,9.564,21.762,9.039,21.343,8.661z",
  "primaryAction": {
    "type": "SetValue",
    "componentId": "textToUpdate",
    "property": "text",
    "value": "${exampleData.imageStyleText}"
  }
}

The following full document example uses data array inflation to display four icon buttons with different combinations of the buttonStyle and contained properties.

Last updated: Dec 13, 2022