APL Image

In Alexa Presentation Language (APL), an Image component draws a bitmap image on the screen. Don't use animated .gif files in your skills. Although these images might appear animated in the simulator, their behavior on screen devices with Alexa might 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 isn't supported for dimension-related properties on Image. If you use auto, the image might not render.

All images must specify a width and a height value. To minimize errors, the width and height of an Image component default to 100dp.

The source / sources property of the Image component is an array of one or more image URLs. The Image component doesn't render until after all the URLs in the array have loaded. After all URLs load, the component applies any filters defined in the filters property. When the filters property is empty or not provided, the component renders the last image in the sources array.

Filters modify, augment, and merge images from the image array. The result of filter processing is a single image. The image that results from filter processing can be further modified by the overlayColor and overlayGradient properties.

For details about image filters, see Filters.

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. Contains an array if multiple images are provided

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

borderRadius

A uniform clipping radius to be set on the corners of the image. Setting the borderRadius to a large number creates a circular clip.

filter, filters

One or more filtering operations to apply to the image. For details, see Filters.

onFail

Commands to run when any of the requested URLs in sources fails to load. The event contains a single source. If multiple sources fail to load, for example when using a filter, one source triggers the event.

The handler runs one time. After the handler runs, the component is considered invalid. Setting a new value to the sources property can trigger the handler again. The onFail handler runs at most one time for any new sources value.

The onFail handler doesn't affect the display status of the component and the display status doesn't affect the handler. For example, when the display property for the Image component is invisible the component takes up space but doesn't display. The device still attempts to load the image and runs the commands in onFail if the image source fails to load.

The onMount handler for the component runs regardless of whether onFail runs. The onMount handler runs in this scenario because the component can mount and display before or after the component loads the image source.

The onFail handler generates an event with the following form:

"event": {
  "source": {
    "type": "Image",
    "handler": "Fail",
    ...                   // Component source properties
  },
  "value": STRING,        // The url of the image source that failed to load
  "error": STRING,        // The reason of failure
  "errorCode": Number     // Error identifier
}

Refer to Event source for a description of event.source properties.

The onFail event handler runs in fast mode in the component data-binding context.

onLoad

Commands to run after all the requested URLs in sources load.

Setting a new value to the sources property can trigger the handler to run again. The onLoad handler runs at most one time for any new 'sources' value.

The onLoad handler doesn't affect the display status of the component and the display status doesn't affect the handler. For example, when the display property for the Image component is invisible the component takes up space but doesn't display. The device still attempts to load the image and runs the commands in onLoad after the image source loads.

The onMount handler for the component runs regardless of whether onLoad runs. The Image component can mount and display before or after the component loads the image source.

The onLoad handler generates an event with the following form:

"event": {
    "source": {
        "type": "Image",
        "handler": "Load",
        ...                   // Component source properties
    }
}

Refer to Event source for a description of event.source properties.

The onLoad event handler runs in fast mode in the component data-binding context.

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.

The overlayColor property 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 remaining 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 remaining after image scaling and alignment.

scale

Scales the image within the container.

The following example illustrates the scale options with different images. The Frame defines a box with a green border. The Image component displays inside the Frame and uses the height and width of the Frame to define the bounding box. Click the Change Scale button to cycle through each of the scale options. Click the Change Image button to view different images fit within the same bounding box.

source, sources

The URL of the image to download and display.

APL supports the following url schemes for images:

• https – Use https instead of http. Many Alexa devices don't support the http scheme in skill APL documents for security reasons.
• data – (2024.3 and later) Alexa devices support the data scheme for embedding image types.

data

For the full data scheme definition, see RFC2397. APL supports embedding of image types through the base64 extension. See RFC4648 Section 4 for the definition of base64 encoding.

Supported grammar:

dataurl   ::=  "data:" mediatype ";base64" "," data
mediatype ::=  "image" "/" subtype ( ";" parameter )*
data      ::=  b64char*
parameter ::=  attribute "=" value
b64char   ::=  [+/=a-zA-Z0-9-]

For details about subtype, attribute and value, see RFC2045.

The following example uses the data URL scheme to display the Alexa logo in a document. See the Data Sources tab for the full data value used for image shown in this example.

Consider the following before you use data URLs for images:

1. Some APL runtimes might impose limits on how long the url or it's components can be. For more details, see RFC1866.
2. If you include multiple data URLs in an APL document, the document might exceed skill response size limit. Consider moving larger resources to a separate package. For details, see Host Layouts, Graphics, and Other Resources in an APL Package. For skill response size limits, see Response format.
3. For image subtypes, use BMP, PNG, and JPEG. Alexa devices might not support other image subtypes.
4. An image sourced by the data URL doesn't use HTTP caching.

Array definition

You can set the source property to an array of URLs instead of a single string. When the filters property is empty, the component displays the last image in the array. When the filters property contains one or more filters, the filter determines which image or images to use in the array. For details about filters, see Filters.

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

The following example shows an Image component. The bounding box for the Image is 300 x 300 pixels. The large value for borderRadius clips the image to a circle. The image fills a 300x300 box on the screen.

Related topics

• Alexa Image Responsive Component
• Frame
• Filters
• Alexa Design Guide: Alexa Presentation Language

Last updated: Dec 18, 2024