Press State (Widget)

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

The Alexa press state responsive component AlexaPressState creates an area over the entire widget that users can tap. The component displays a subtle animation when tapped to provide the user with feedback. You configure AlexaPressState to either fill the entire widget viewport, or leave enough space for your header and footer.

Other than the feedback on tap, AlexaPressState doesn't display any visual components on its own. Use AlexaPressState in addition to your own design or a template to display content.

Compatibility

AlexaPressState is designed to work with the following widget viewport profiles in the alexa-viewport-profiles package:

Widget Medium (@hubWidgetMedium)

If you use AlexaPressState on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Note: Don't use AlexaPressState with AlexaTextList or AlexaTextListItem. The list components display visual feedback when the user taps each item.

Import the alexa-layouts package

To use AlexaPressState, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaPressState was introduced in version 1.5.0.

AlexaPressState parameters

The following table shows the AlexaPressState properties that work with the widget viewport profiles. Not all parameters apply to all viewport profiles. The "Widget support" column indicates the widget viewport profiles that support each parameter. For details about viewport profiles, see Viewport Profiles.

All parameters except type are optional.

Name	Type	Default	Description	Widget support	Version added
`hasFooterButton`	Boolean	`false`	When `true`, leave space at the bottom of the tap target for an `AlexaFooterActionButton` component. Ignored when `items` has a value. For details, see Combine with AlexaHeader and AlexaFooterActionButton.	Medium	1.5.0
`hasHeader`	Boolean	`true`	When `true`, reduce the size of the tap target so that the header area isn't included in the press state tap target. Set `headerTitle` and `headerTitleCanUseTwoLines` to the same values you provide in the `AlexaHeader` component. The `AlexaPressState` component uses these values to calculate correct amount space. Ignored when `items` has a value.	Medium	1.5.0
`headerTitle`	String	—	Applies when `hasHeader` is `true`. Used to reduce the size of the tap target so that the header area isn't included in the press state tap target. Set to the same string you provide in the `headerTitle` property of the `AlexaHeader` component. Note: `AlexaPressState` doesn't display the text you set in this property.	Medium	1.5.0
`headerTitleCanUseTwoLines`	Boolean	`false`	Applies when `hasHeader` is `true`. Used to reduce the size of the tap target so that the header area isn't included in the press state tap target. Set to the same value you provide in the `headerTitleCanUseTwoLines` property of the `AlexaHeader`.	Medium	1.5.0
`items`	Array	—	An array of child components or layouts to display. If you provide more than one item in the array, `AlexaPressState` displays the first item where `when` evaluates to `true`. When `items` contains a value, the `hasFooterButton` and `hasHeader` parameters are ignored and `AlexaPressState` creates an area that users can tap that covers the entire widget. For details, see AlexaPressState placement.	Medium	1.5.0
`primaryAction`	Array of commands	—	The action to trigger when the user taps the widget.	Medium	1.5.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	Medium	1.5.0
`type`	String	—	Always set to `AlexaPressState`.	Medium	1.5.0

AlexaPressState placement

When you place AlexaPressState in your document, perform do one of the following actions:

Nest your layout within AlexaPressState.
Place AlexaPressState after your layout.

Nest your layout within AlexaPressState

Place AlexaPressState as the top-level component in mainTemplate or a top-level Container, and then pass a component for your design in the items property. AlexaPressState wraps your components and creates an area users can tap over your entire layout.

The following example shows the structure with AlexaPressState as the top-level component.

mainTemplate
    AlexaPressState
        Container
            Items to define your layout

The following example shows the structure with AlexaPressState in a top-level Container.

mainTemplate
    Container
        AlexaPressState
            Container
                Items to define your layout

AlexaPressState displays a single child component. Use a Container if your layout requires multiple child components.

Place AlexaPressState after your layout

Place AlexaPressState after the other components in your design. AlexaPressState overlays the preceding components with the area users can tap.

With this option, you can use the hasHeader and hasFooterButton properties to constrain the size of the area users can tap. This enables you to then define the header or footer button as separate areas users can tap to invoke different commands.

The following example shows the placement of AlexaPressState after the other components.

mainTemplate
    Container
        Items to define your layout
        AlexaPressState

Combine with the AlexaFooterActionButton

You can combine AlexaFooterActionButton with AlexaPressState to create multiple tap targets for your widget. This also works if you use a template that incorporates the AlexaFooterActionButton, such as AlexaPhoto.

To use AlexaFooterActionButton with AlexaPressState

Position AlexaPressState after all the components in your design.
Set the following properties on AlexaPressState:
- primaryAction – The commands to run for the main tap target.
- hasFooterButton – true.
Include AlexaFooterActionButton as part of your design.
Set the primaryAction property on AlexaFooterActionButton to the command to run when the user taps the footer button.

AlexaPressState examples

The following example shows a widget with two areas users can tap. The example uses AlexaPhoto to display a photo with text. For AlexaPhoto, you include the footer action button by setting buttonText and primaryAction. Because hasHeader is true, the press state area doesn't cover the header area.

The following example shows a similar widget, but with one area users can tap. The example uses AlexaPhoto and displays a header. Tapping anywhere in the widget activates the AlexaPressState commands.

Was this page helpful?

Provide feedback

Last updated: Dec 06, 2023