Press State (Widget)


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.

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

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

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

  1. Position AlexaPressState after all the components in your design.
  2. Set the following properties on AlexaPressState:
    • primaryAction – The commands to run for the main tap target.
    • hasFooterButtontrue.
  3. Include AlexaFooterActionButton as part of your design.
  4. 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?

Last updated: Dec 06, 2023