APL Image (APL 1.3 and Earlier)
(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)
An Image
component draws a bitmap image on the screen. Do not use animated .gif files in your skills. Although these images may appear animated in the simulator, their behavior on screen devices with Alexa may be different.
Properties
The Image component has the following properties in addition to the base component properties. See the meaning of the columns.
The "auto" value is not supported for dimension-related properties, and if used, the image may not render.
Property | Type | Default | Styled | Dynamic | Description |
---|---|---|---|---|---|
align |
Alignment | center |
Yes | No | Alignment of the image within the containing box. |
borderRadius |
Non-negative Absolute dimension | 0 | Yes | No | Clipping radius for the image. |
filter , filters |
Array of filters | [ ] | No | No | Filters to apply to the image. |
overlayColor |
Color | none | Yes | Yes | If set, a theme-appropriate scrim is overlaid on the image. This ensures text placed on the image is legible. |
overlayGradient |
Gradient | none | Yes | No | A colored gradient that overlays the image. |
scale |
Scale | best-fit |
Yes | No | How the image will be resized to fit in the bounding box. |
source |
URL | none | No | Yes | URL to download the image from. |
All images must specify a width and a height value. To minimize errors, the width and height of an Image component default to 100dp.
When the Image
component is the target of an event, event.target
reports the following values:
"event": {
"target": {
"disabled": Boolean, // True if the image is disabled
"height": Number, // Height of the component, in dp (includes the padding)
"id": ID, // ID of the component
"uid": UID, // Runtime-generated unique ID of the component
"opacity": Number, // Opacity of the component [0-1]
"source": URL, // Source URL of the displayed image
"width": Number, // Width of the component, in dp (includes the padding)
}
}
align
Positions the image within the container.
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 |
borderRadius
A uniform clipping radius to be set on the corners of the image. Setting the borderRadius to a large number will create a circular clip.
filter(s)
One or more filtering operations to apply to the image. See Filter.
overlayColor
A color applied as a scrim across the image. The color must have a transparent component for the image to show. For instance, you could set overlayColor
to rgba(white,0.3)
to overlay the image with white at 30% opacity.
Note that overlayColor
is a convenience name for a filter that overlays the image with a single color. The overlayColor
filter is applied after any filters defined by the filter property.
The scrim applies only to the drawn area of the image, not the padding or any blank space left over after image scaling and alignment.
overlayGradient
A gradient applied as a scrim across the image. The gradient must have a transparent component for the image to show. An overlayGradient
is equivalent to a filter that overlays the image with a named gradient. The overlayGradient
filter is applied after any filters defined by the filter
property and after the overlayColor
property.
The gradient applies only to the drawn area of the image, not the padding or any blank space left over after image scaling and alignment.
scale
Scales the image within the container.
Name | Description |
---|---|
none |
Does not scale the image. The align property is used to position the image in the bounding box. The portions of the image that fall outside of the bounding box are clipped. |
fill |
Scales the image non-uniformly so that the width matches the bounding box width and the height matches the bounding box height. |
best-fill |
Scales the image uniformly up or down so that the bounding box is completely covered. The align property is used to position the scaled image within the bounding box. |
best-fit |
Scales the image uniformly up or down so that the entire image fits within the bounding box. The align property is used to position the scaled image within the bounding box. |
best-fit-down |
Scales the image uniformly as per best-fit , but only allow down-scaling, never up-scaling. This ensures that the image will not appear pixelated. |
source
The URL of the image to be downloaded and displayed.
Manage alignment, scaling, and sizing of images
Image alignment and scaling can be complex. Images must have a specified height and width. The actual image must then be clipped, scaled, and positioned within the bounding box of the Image component.
The scale
mode controls how the image size is adjusted to fit the bounding box.
The align
mode controls how the image (after scaling) is positioned in the box.
Any clipping is always applied to the bounding box, not to the scaled image.
Sample image
{
"type": "Image",
"source": "http://images.example.com/image/foo.png",
"scale": "fill",
"width": 300,
"height": 300
}
In this case, the image will fill a 300x300 box on the screen.
Last updated: Nov 28, 2023