Background

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

The Alexa background responsive component (AlexaBackground) displays a video, image, or color behind your content.

Import the alexa-layouts package

To use AlexaBackground, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.6.0. AlexaBackground was introduced in version 1.1.0.

AlexaBackground Parameters

All parameters except type are optional.

Name	Type	Default	Description	Version added
`backgroundAlign`	String	`center`	Image/video alignment to apply to the background image or video.	1.1.0
`backgroundBlur`	Boolean	`false`	When `true`, display the provided background image with a blur effect. Applies when `backgroundImageSource` contains a value.	1.1.0
`backgroundColor`	Color	—	Color to use as a background color. Used when neither `backgroundImageSource` or `backgroundVideoSource` contain values.	1.1.0
`backgroundImageSource`	String	—	URL for the background image source. Used when `backgroundVideoSource` isn't provided.	1.1.0
`backgroundScale`	String	`best-fill`	Image or video scaling to apply to background image or video.	1.1.0
`backgroundVideoSource`	Video source	—	The background video source. Provide a source in the same format shown for the `source` property of the Video component	1.1.0
`colorOverlay`	Boolean	`false`	When `true`, apply a scrim to the background to make it easier to read the text displayed over the image or video.	1.1.0
`entities`	Array	—	Array of entity data to bind to this component.	1.2.0
`overlayGradient`	Boolean	`false`	When `true`, apply a gradient to the background.	1.1.0
`overlayNoise`	Boolean	`false`	When `true`, apply the Noise filter to the background image.	1.1.0
`type`	String	—	Always set to `AlexaBackground`	1.1.0
`videoAudioTrack`	String	`foreground`	Audio track to play on when playing the video. Can be `foreground` \| `background` \| `none`	1.1.0
`videoAutoPlay`	Boolean	`false`	When `true`, the video begins playing automatically when the document renders on the device. Applies when `backgroundVideoSource` contains a value.	1.1.0

Background source priority

You can provide more than one background source (video, image, and color). Alexa chooses the background to show based on this priority:

backgroundVideoSource
backgroundImageSource
backgroundColor

If you don't provide a value for any of these, a default background is used.

Position other components relative to the background

To display the background on the full viewport behind your other content, place the AlexaBackground layout first in the top-level Container and set the Container height and width to 100%.

For example, the following Container contains three items: AlexaBackground, AlexaHeader, and then a Text component. The plain dark red background fills the entire screen. The header text displays at the top over the background, and the text string displays further down on the screen.

AlexaBackground example

The following example displays a video background. The video starts automatically when the device renders the document and then plays through two times (repeatCount). (This example uses a fictitious backgroundVideoSource. Replace with the URL of the video you want to display).

{
  "type": "AlexaBackground",
  "backgroundVideoSource": [
    {
      "url": "https://example.com/fictitious-video-urls/background-video.mp4",
      "repeatCount": 2
    }
  ],
  "videoAutoPlay": true,
  "videoAudioTrack": "none"
}

The following example displays an image background instead of a video.

Last updated: Mar 02, 2023