Image

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

The Alexa image responsive component (AlexaImage) displays an image. You can display the image with standard aspect ratios (such as portrait or round) and effects such as rounded corners.

Import the alexa-layouts package

To use AlexaImage, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.5.0. AlexaImage was introduced in version 1.1.0.

Use the Other Versions option at the top of this page to see documentation for different versions of AlexaImage. The table of parameters notes the version of alexa-layouts in which each parameter was added.

AlexaImage parameters

All parameters except type are optional. You must also provide either imageHeight or imageWidth, but you do not need to provide both.

Name	Type	Default	Description	Version added
`imageAlignment`	String	center	Determines how to position the image within the bounding box. Used when the image is smaller than the bounding box. Options are bottom, bottom-left, bottom-right, center, left, right, top, top-left, top-right.	1.1.0
`imageAspectRatio`	String	square	Aspect ratio to use for the image bounding box. This applies when you provide either `imageHeight` or `imageWidth`, but not both. Options are square, round, standard_landscape, standard_portrait, poster_landscape, poster_portrait, widescreen.	1.1.0
`imageBlurredBackground`	Boolean	false	When true, display a blurred version of the image behind the image. size. Ignored when `imageScale` is set to `fill` or `best-fill`.	1.1.0
`imageHeight`	Dimension	none	Height of the image bounding box. The image is scaled to fit within this height using the `imageScale` setting.	1.1.0
`imageScale`	String	best-fit	Determines how to scale the image to fit within the bounding box. Options are none, fill, best-fit, best-fill, best-fit-down.	1.1.0
`imageWidth`	Dimension	none	Width of the image bounding box. The image is scaled to fit within this width using the `imageScale` setting.	1.1.0
`entities`	Array	[]	Array of entity data to bind to this component.	1.2.0
`imageRoundedCorner`	Boolean	true	When true, use rounded corners for the image.	1.1.0
`imageShadow`	boolean	true	When true, display a drop shadow behind the image.	1.3.0
`imageSource`	String	none	URI for the image	1.1.0
`type`	String	None	Always set to `AlexaImage`	1.1.0

imageHeight / imageWidth

These parameters are dimensions that set the height and width of the bounding box for the image. AlexaImage then scales the image to fit within the box according to imageScale option and positions the image as specified in the imageAlignment option.

At a minimum, you must provide either imageHeight or imageWidth.

When you provide both, the image bounding box has the specified dimensions.
When you provide just one, AlexaImage calculates the other dimension based on the specified imageAspectRatio.

imageAlignment

Determines how to align the image within the bounding box. This is used when the image to display is smaller than the bounding box.

The imageAlignment parameter accepts the following options.

Name	Description
`bottom`	Align to the bottom, horizontally centered
`bottom-left`	Align the bottom-left corners
`bottom-right`	Align the bottom-right corners
`center`	Center horizontally and vertically
`left`	Align to the left side, vertically centered
`right`	Align to the right side, vertically centered
`top`	Align to the top, horizontally centered
`top-left`	Align the top-left corners
`top-right`	Align the top-right corners

imageAspectRatio

Determines the aspect ratio and size of the image bounding box when you set only one of imageHeight or imageWidth.

The imageAspectRatio parameter accepts the following options.

Name	Ratio
square	1:1
round	1:1
standard_landscape	4:3
standard_portrait	3:4
poster_landscape	3:2
poster_portrait	2:3
widescreen	16:9

When you set just one dimension ( imageHeight or imageWidth), AlexaImage calculates the size of the other dimension so that the resulting bounding box matches the specified aspect ratio. For example, if imageWidth is 300dp and imageAspectRatio is standard_landscape, the resulting image bounding box is 300dp wide by 400dp tall and therefore has a 4:3 aspect ratio.

When you provide both imageWidth and imageHeight, AlexaImage uses your provided dimensions for the image bounding box size, so imageAspectRatio is ignored.

Note that imageAspectRatio determines the aspect ratio of the bounding box for your image. The bounding box size and aspect ratio does not need to match the actual aspect ratio of the source image. For example, you can set imageAspectRatio to square and pass in an imageSource that references a landscape image. The imageScale then determines how to fit that image within the box. For examples, see Image aspect ratios and scaling examples.

imageBlurredBackground

When true, displays a blurred version of the image behind the image. The background is visible when the image bounding box is larger than the actual scaled image. This is typically the case when you use best-fit or best-fit-down for the imageScale setting. The none scaling option can also display the background when the image is smaller than the bounding box. Since fill and best-fill scale the image to completely fill the bounding box, imageBlurredBackground is ignored for those scaling options.

The imageBlurredBackground property is useful when you want to display a variety of images of different sizes in a consistently-sized box, such as a list of images. The blurred background can fill in the space so that the same sized box works for any sized image.

For examples of the differences between best-fit and best-fill, see Image aspect ratios and scaling examples.

imageScale

Determines how to scale the image to fit within the bounding box. The imageScale property accepts the following options.

Name	Description
`none`	Do not scale the image. `AlexaImage` positions the image within the bounding box according to the `imageAlign` property. The portions of the image that fall outside of the bounding box are clipped.
`fill`	Scale the image non-uniformly so that the width matches the bounding box width and the height matches the bounding box height.
`best-fill`	Scale the image uniformly up or down so that the bounding box is completely covered. `AlexaImage` positions the scaled image within the bounding box according to the `imageAlign` property.
`best-fit`	Scale the image uniformly up or down so that the entire image fits within the bounding box. `AlexaImage` positions the scaled image within the bounding box according to the `imageAlign` property.
`best-fit-down`	Scale the image uniformly as per `best-fit`, but only allow down-scaling, never up-scaling. This ensures that the image does not appear pixelated.

For examples of the differences between best-fit and best-fill, see Image aspect ratios and scaling examples.

Image aspect ratios and scaling examples

The following examples illustrate the different imageAspectRatio options with the same source image. All the examples use the following landscape image:

A landscape image — Landscape image used in the `imageAspectRatio` examples

Each example has these settings:

imageWidth — 300dp; imageHeight is left not set
imageAlignment — center (ignored for best-fill)
imageBlurredBackground — true (ignored for best-fill)
imageRoundedCorner — false
imageAspectRatio — one of the imageAspectRatio options, as noted in the table row
imageScale — best-fit or best-fill, as noted in the table column heading

For an APL document that produces these images, see AlexaImage example.

imageAspectRatio	Best fit	Best fill
`square`
`standard_portrait`
`standard_landscape`
`poster_landscape`
`widescreen`

Note that the standard_landscape, poster_landscape, and widescreen examples still must scale the image to fit. Although the source image has a landscape orientation, the image's actual aspect ratio does not exactly match the 4:3 (standard_landscape), 3:2 (poster_landscape), or 16:9 (widescreen) aspect ratios defined with imageAspectRatio. The source image is closest to the widescreen option, so that example shows very little scaling.

AlexaImage example

This example displays a square in the center of the viewport. The square is filled with a blurred copy of the image, then the full image is scaled to fit within the square. Change the imageAspectRatio and imageScale properties to see the examples shown in Image aspect ratios and scaling examples.