Header

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

The Alexa header responsive component (AlexaHeader) displays common header information such as a title, subtitle, and back button.

Compatibility

AlexaHeader is designed to work with the following viewport profiles:

The following widget viewport profiles in the alexa-viewport-profiles package:
- Widget Medium (@hubWidgetMedium)
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

For details about viewport profiles, see Viewport Profiles.

If you use AlexaHeader on an unsupported viewport, you might have unexpected results.

Differences for widgets

When used within a widget, AlexaHeader displays a simplified header to accommodate the small widget size. The header has the following characteristics:

The header displays header title text, but not attribution text, attribution images, or subtitles.
The header doesn't support the back button.

Import the alexa-layouts package

To use AlexaHeader, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaHeader was introduced in version 1.0.0.

AlexaHeader parameters

The following table shows the parameters you can set on AlexaHeader. Unless otherwise noted, standard viewport profiles support all parameters. 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
`entities`	Array	—	Array of entity data to bind to this component.	Medium	1.2.0
`headerAttributionImage`	String	—	URL for attribution image source. Displays when `headerAttributionPrimacy` is `true`, or on a device that shows Title/Subtitle and Attribution.	Not supported	1.0.0
`headerAttributionOpacity`	Number	`0.8`	The opacity of the attribution text and attribution image. Set to a number between 0 and 1.	Not supported	1.3.0
`headerAttributionPrimacy`	Boolean	`true`	When `true`, display the `headerAttributionImage` on devices that display a single element due to screen size. When `false`, display the `headerTitle` and `headerSubtitle`.	Not supported	1.0.0
`headerAttributionText`	String	—	Attribution text to render in the header. Shown when `headerAttributionImage` doesn't have a value and `headerAttributionPrimacy` is `true`, or on a device that shows both Title/Subtitle and Attribution.	Not supported	1.0.0
`headerBackButton`	Boolean	`false`	When `true`, display a back button in the header.	Not supported	1.0.0
`headerBackButtonAccessibilityLabel`	String	`Back`	An accessibility label to describe the back button to customers who use a screen reader.	Not supported	1.1.0
`headerBackButtonCommand`	Command	`{"type":"SendEvent","arguments":["goBack"]}`	Command to run when the user selects the back button.	Not supported	1.1.0
`headerBackgroundColor`	String	`transparent`	Optional color value to use as the background color for the header.	Medium	1.0.0
`headerDivider`	Boolean	`false`	When `true`, display a divider below the header to help separate it from content.	Not supported	1.1.0
`headerHorizontalAlignmentCentered`	boolean	`false`	When `true`, use 'center' horizontal alignments for the contents in the header.	Medium	1.6.0
`headerSubtitle`	String	—	Secondary text to render in header.	Not supported	1.0.0
`headerTitle`	String	—	Primary text to render in the header.	Medium	1.0.0
`headerTitleCanUseTwoLines`	Boolean	`false`	When `true`, long `headerTitle` text in a widget can wrap to two lines when needed. Applies to widget viewport profiles only. Ignored when displayed on a standard APL viewport.	Medium	1.5.0
`layoutDirection`	String	`${environment.layoutDirection}`	Specifies the layout direction for the content. Set this property to either `LTR` (left-to-right) or `RTL` (right-to-left). This property doesn't inherit the `layoutDirection` from the component's parent container. Therefore, explicitly set this property when needed. For more details about support for right-to-left languages in the responsive components, see Support for Right-to-left Languages.	Medium	1.4.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	Medium	1.1.0
`type`	String	—	Always set to `AlexaHeader`	Medium	1.0.0

Note: If both headerAttributionText and headerAttributionImage parameters are provided, the document displays the headerAttributionImage.

When both the Title/Subtitle and Attribution properties are provided, and headerHorizontalAlignmentCentered is set to true

If headerAttributionPrimacy is set to true, only the Attribution is displayed.
If headerAttributionPrimacy is set to false, only Title/Subtitle is displayed.

AlexaHeader examples

{
  "type": "AlexaHeader",
  "headerBackgroundColor": "red",
  "headerTitle": "This is the header title",
  "headerSubtitle": "This is the header subtitle",
  "headerAttributionText": "Attribution text"
}

The following example of AlexaHeader uses the widget-only headerTitleCanUseTwoLines property to display a longer header in a widget.

{
  "type": "AlexaHeader",
  "headerBackgroundColor": "red",
  "headerTitle": "Long headerTitle text that uses 2 lines on a widget",
  "headerTitleCanUseTwoLines": true
}

Example of AlexaHeader with a red background and longer header title

Last updated: Mar 02, 2023