Image List Item (1.1.0)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

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

The Alexa image list item responsive component (AlexaImageListItem) displays an image along with text, formatted to display within a list. This component uses the AlexaImage responsive component to size and format the item. Display a list of AlexaImageListItem items with the AlexaImageList responsive template.

Import the alexa-layouts package

To use AlexaImageListItem, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaImageListItem was introduced in version 1.1.0.

AlexaImageListItem parameters

All parameters except type are optional.

Name	Type	Default	Description	Version added/updated
`defaultImageSource`	String		URI a default image to use when `imageSource` isn't provided. Provide a `defaultImageSource` to make sure that image containers are never empty.	1.1.0
`hideOrdinal`	Boolean	`false`	When `true`, don't display a number next to the list item.	1.1.0
`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. This property works the same as the `imageAlignment` property for the `AlexaImage` responsive component.	1.1.0
`imageAspectRatio`	String	`square`	Aspect ratio to use for the image bounding box for the item. Options are square, round, standard_landscape, standard_portrait, poster_landscape, poster_portrait, widescreen. This property works the same as the `imageAspectRatio` property for the `AlexaImage` responsive component except that the height and width of the bounding box are pre-defined based on the aspect ratio and can't be changed.	1.1.0
`imageBlurredBackground`	Boolean	`false`	When `true`, display a blurred version of the image behind the image. Ignored when `imageScale` is set to `fill` or `best-fill`. This property works the same as the `imageBlurredBackground` property for the `AlexaImage` responsive component.	1.1.0
`imageHideScrim`	Boolean	`false`	When `true`, hide the overlay (scrim) between image and text content.	1.1.0
`imageMetadataPrimacy`	Boolean	`false`	When `true`, prioritize `secondaryText` and `tertiaryText` over `hintText` on devices that can display one element due to screen size. When `false`, `secondaryText`, and `tertiaryText` are hidden on small screens.	1.1.0
`imageProgressBarPercentage`	Number	0	When set to a number from 1 to 100, display a progress bar on the image based on the provided percentage. This gives the user a glanceable status for the item. The progress bar displays when `imageShowProgressBar` is `true` and the `imageProgressBarPercentage` parameter is set to a value greater than 0. The progress bar doesn't display when the `imageAspectRatio` is `round`.	1.1.0
`imageRoundedCorner`	Boolean	`true`	When `true`, use rounded corners for the image.	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. This property works the same as the `imageScale` property for the `AlexaImage` responsive component.	1.1.0
`imageShowProgressBar`	Boolean	`true`	Toggle to display the progress bar on the image overlay. The progress bar displays when `imageShowProgressBar` is `true` and the `imageProgressBarPercentage` parameter is set to a value greater than 0. The progress bar doesn't display when the `imageAspectRatio` is `round`.	1.1.0
`imageSource`	String		URI for the image to display.	1.1.0
`primaryAction`	Command		The action to trigger when the user selects the list item.	1.1.0
`primaryText`	String		Primary text to display for the list item.	1.1.0
`providerText`	String		Provider text to display over the image.	1.1.0
`secondaryText`	String		Secondary text for the list item.	1.1.0
`tertiaryText`	String		Tertiary text for the list item.	1.1.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	1.1.0

Image size, aspect ratio, and scaling

The AlexaImageListItem responsive component uses a pre-defined height and width, determined by the `imageAspectRatio you provide and the characteristics of the viewport.

The aspect ratio, scaling, and alignment work the same way they do for the AlexaImage responsive component. For details, see Image aspect ratios and scaling examples.

AlexaImageListItem example

The following example shows an AlexaImageListItem with all text options and the progress bar.

{
  "type": "AlexaImageListItem",
  "theme": "dark",
  "primaryText": "${exampleData.primaryText}",
  "secondaryText": "${exampleData.secondaryText}",
  "tertiaryText": "${exampleData.tertiaryText}",
  "providerText": "${exampleData.providerText}",
  "imageProgressBarPercentage": 75,
  "imageRoundedCorner": true,
  "imageAspectRatio": "square",
  "imageSource": "${exampleData.imageSource}"
}

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023