Background

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

Compatibility

AlexaBackground 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.

Differences for widgets

Widgets don't support playing video, so AlexaBackground doesn't support using a video background when used in a widget.

Import the alexa-layouts package

To use AlexaBackground, import the alexa-layouts package.

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

AlexaBackground Parameters

The following table shows the parameters you can set on AlexaBackground. 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

backgroundAlign

String

center

Image/video alignment to apply to the background image or video.

Medium

1.1.0

backgroundBlur

Boolean

false

When true, display the provided background image with a blur effect. Applies when backgroundImageSource contains a value.

Medium

1.1.0

backgroundColor

Color

—

Color to use as a background color. Used when neither backgroundImageSource or backgroundVideoSource contain values.

Medium

1.1.0

backgroundImageSource

String

—

URL for the background image source. Used when backgroundVideoSource isn't provided.

Medium

1.1.0

backgroundScale

String

best-fill

Image or video scaling to apply to background image or video.

Medium

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

Not supported

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.

Medium

1.1.0

entities

Array

—

Array of entity data to bind to this component.

Medium

1.2.0

overlayGradient

Boolean

false

When true, apply a gradient to the background.

Medium

1.1.0

overlayNoise

Boolean

false

When true, apply the Noise filter to the background image.

Medium

1.1.0

type

String

—

Always set to AlexaBackground

Medium

1.1.0

videoAudioTrack

String

foreground

Audio track to play on when playing the video. Can be foreground | background | none

Not supported

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.

Not supported

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:

  1. Display the backgroundVideoSource when it's provided.
  2. Display the backgroundImageSource when the backgroundVideoSource isn't provided.
  3. Display the backgroundColor when neither the backgroundVideoSource or backgroundImageSource are provided.
  4. Use a default background when none of backgroundVideoSource, backgroundImageSource or backgroundColor are provided.

Widgets don't support video, so for a widget, Alexa uses the same priority to choose between backgroundImageSource, backgroundColor, and the default background.

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.

The following example shows an image background on a widget.

Was this page helpful?

Last updated: Dec 06, 2023