APL Image (APL 1.4)

(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 is the source or target of an event, the following values are reported in event.source or event.target:

{
  // Image-specific values
  "type": "Image",
  "url": URL,          // The URL of the image

  // General component values
  "bind": Map,         // Access to component data-binding context
  "checked": Boolean,  // Checked state
  "disabled": Boolean, // Disabled state
  "focused": Boolean,  // Focused state
  "height": Number,    // Height of the component, in dp (includes the padding)
  "id": ID,            // ID of the component
  "opacity": Number,   // Opacity of the component [0-1]
  "pressed": Boolean,  // Pressed state
  "uid": UID,          // Runtime-generated unique ID of the component
  "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, filters

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 download and display.

Use https instead of http for image source URLs. Many Alexa devices don't support the http scheme in skill APL documents for security reasons.

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": "https://images.example.com/image/foo.png",
 "scale": "fill",
 "width": 300,
 "height": 300
}

In this case, the image fills a 300x300 box on the screen.

Was this page helpful?

Last updated: Nov 28, 2023