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 |
---|---|---|---|---|
String |
|
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 | |
String |
|
Aspect ratio to use for the image bounding box. This applies when you provide either |
1.1.0 | |
Boolean |
|
When |
1.1.0 | |
— |
Height of the image bounding box. The image is scaled to fit within this height using the |
1.1.0 | ||
String |
|
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 | |
— |
Width of the image bounding box. The image is scaled to fit within this width using the |
1.1.0 | ||
|
Array |
— |
Array of entity data to bind to this component. |
1.2.0 |
|
Boolean |
|
When |
1.1.0 |
|
Boolean |
|
When |
1.3.0 |
|
String |
— |
URI for the image. |
1.1.0 |
|
String |
— |
Always set to |
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 specifiedimageAspectRatio
.
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:
Each example has these settings:
imageWidth
— 300dp;imageHeight
is left not setimageAlignment
—center
(ignored forbest-fill
)imageBlurredBackground
—true
(ignored forbest-fill
)imageRoundedCorner
—false
imageAspectRatio
— one of theimageAspectRatio
options, as noted in the table rowimageScale
—best-fit
orbest-fill
, as noted in the table column heading
For an APL document that produces these images, see AlexaImage example.
imageAspectRatio | Best fit | Best fill |
---|---|---|
|
||
|
||
|
||
|
||
|
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.
Related topics
Last updated: Nov 28, 2023