Image

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

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.

Compatibility

AlexaImage is designed to work with 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

If you use AlexaImage on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Import the alexa-layouts package

To use AlexaImage, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.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	Widget support	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.	Not supported	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.	Not supported	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`.	Not supported	1.1.0
`imageHeight`	Dimension	—	Height of the image bounding box. The image is scaled to fit within this height using the `imageScale` setting.	Not supported	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.	Not supported	1.1.0
`imageWidth`	Dimension	—	Width of the image bounding box. The image is scaled to fit within this width using the `imageScale` setting.	Not supported	1.1.0
`accessibilityLabel`	String		A string describing the image. Voice over reads this string when the user selects this component.	Not supported	1.7.0
`entities`	Array	—	Array of entity data to bind to this component.	Not supported	1.2.0
`gradientLowerInputRange`	Number	0.3	Specifies the end of the gradient `inputRange`. Applies when `overlayGradient` is `true`. For details about the `inputRange` property of a gradient, see Gradient.	Not supported	1.6.0
`imageRoundedCorner`	Boolean	`true`	When `true`, use rounded corners for the image.	Not supported	1.1.0
`imageShadow`	Boolean	`true`	When `true`, display a drop shadow behind the image.	Not supported	1.3.0
`imageSource`	String	—	URI for the image.	Not supported	1.1.0
`overlayGradient`	Boolean	`false`	When `true`, apply a gradient to the image.	Not supported	1.6.0
`type`	String	—	Always set to `AlexaImage`.	Not supported	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.

Last updated: Dec 13, 2022