Image


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
  • imageAlignmentcenter (ignored for best-fill)
  • imageBlurredBackgroundtrue (ignored for best-fill)
  • imageRoundedCornerfalse
  • imageAspectRatio — one of the imageAspectRatio options, as noted in the table row
  • imageScalebest-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.



Was this page helpful?

Last updated: Nov 28, 2023