Image (1.1.0 - 1.5.0)


(This is not the most recent version of AlexaImage. Use the Other Versions option to see the documentation for the most recent version of AlexaImage)

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

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

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

URI for the image.

1.1.0

type

String

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
  • 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