Card

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

The Alexa card responsive component AlexaCard displays an atomic unit of content within a container. Use this component for a glanceable, digestible snapshot of information. You can configure the background, the metadata, and the command to run when the user selects the card.

Compatibility

AlexaCard is designed to work with the following standard viewport profiles in the alexa-viewport-profiles package:

All hub landscape profiles
All hub portrait profiles
All TV profiles

If you use AlexaCard on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Import the alexa-layouts package

To use AlexaCard, import the alexa-layouts package.

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

The AlexaCard component can display icons next to the secondaryText and tertiaryText. To use an icon from the Alexa Icon Library, you must also import the alexa-icon package into your document. The following example shows an import array that imports the latest versions of alexa-layouts and alexa-icon.

{
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    },
    {
      "name": "alexa-icon",
      "version": "1.0.0"
    }
  ]
}

AlexaCard parameters

The following table shows the parameters you can set on AlexaCard. Unless otherwise noted, standard viewport profiles support all parameters. The "Widget support" column indicates the widget viewport profiles that support each parameter. For details about viewport profiles, see Viewport Profiles.

All parameters except type are optional.

Name	Type	Default	Description	Widget support	Version added
`accessibilityLabel`	String	`Item: {imageAltText} {primaryText} {secondaryText} {tertiaryText} {ratings}`	A string describing the card. Voice over reads this string when the user selects the card.	Not supported	1.7.0
`attributionImage`	String	—	URL for attribution image source.	Not supported	1.7.0
`cardBackgroundColor`	Color	—	Background color for the card.	Not supported	1.7.0
`cardId`	String	`cardId`	Unique identifier for this instance of the `Card` component. When you display multiple `Card` components at the same time, such as in a `Sequence`, set `cardId` to a unique ID for each instance.	Not supported	1.7.0
`cardRoundedCorner`	Boolean	`true`	When `true`, display the card with rounded corners.	Not supported	1.7.0
`cardShadow`	Boolean	`true`	When `true`, display a drop shadow for the card.	Not supported	1.7.0
`disabled`	Boolean	`false`	When `true`, this component doesn't respond to touch or focus.	Not supported	1.7.0
`emptyRatingGraphic`	Any	—	The graphic to display to represent an 'empty' rating slot (such as an empty star). Used when `ratingSlotMode` is `multiple`. You can provide either a reference to an AVG or the URL of an image. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	Not supported	1.7.0
`entities`	Any	—	Array of entity data bind to this layout	Not supported	1.7.0
`fullRatingGraphic`	Any	—	The graphic to display to represent a 'full' rating slot (such as a full star). Used when `ratingSlotMode` is `multiple`. You can provide either a reference to an AVG or the URL of an image. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	Not supported	1.7.0
`halfRatingGraphic`	Any	—	The graphic to display to represent a 'half' rating slot (such as a half star). Used when `ratingSlotMode` is `multiple`. You can provide either a reference to an AVG or the URL of an image. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	Not supported	1.7.0
`headerText`	String	—	Header text to display at the top of the card.	Not supported	1.7.0
`imageAltText`	String	—	Alt text for the image. Voice over reads this string.	Not supported	1.7.0
`imageCaption`	Boolean	`false`	When `true`, display the card text over a solid background below the image. When `false`, display the text directly over the image with a gradient scrim to increase the text readability.	Not supported	1.7.0
`imageHideScrim`	Boolean	`false`	When `true`, hide the scrim overlay displayed over the image.	Not supported	1.7.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`, the `imageProgressBarPercentage` parameter is set to a value greater than 0, and the card has an `imageSource`.	Not supported	1.7.0
`imageShowProgressBar`	Boolean	`true`	When `true`, display the progress bar on the image overlay. The progress bar displays when `imageShowProgressBar` is `true`, the `imageProgressBarPercentage` parameter is set to a value greater than 0, and the card has an `imageSource`.	Not supported	1.7.0
`imageSource`	String	—	URI for the image to display.	Not supported	1.7.0
`primaryAction`	Array of commands	—	The action to trigger when the user taps the card.	Not supported	1.7.0
`primaryText`	String	—	Primary text to display.	Not supported	1.7.0
`ratingGraphicType`	String	AVG	The type of graphic to use for the rating. Set to `AVG` or `image`. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	Not supported	1.7.0
`ratingNumber`	Number	—	A numeric rating between 0 and 5. When set to a positive number, displays the number as a star rating. Set to a negative number or omit to leave off the rating.	Not supported	1.7.0
`ratingSlotMode`	String	multiple	Determines whether to display a single graphical asset for the rating, or build the rating from multiple image assets. When set to `single`, provide a single graphical asset in the `singleRatingGraphic` property. When `multiple`, provide the numeric rating in `ratingNumber`. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	Not supported	1.7.0
`ratingText`	String	—	Text to display next to the rating. Ignored when `ratingNumber` is a negative number or omitted.	Not supported	1.7.0
`secondaryIconName`	String	—	Secondary icon name. Set to the name of an icon in the Alexa Icon Library. You must also import the `alexa-icon` package into your document.	Not supported	1.7.0
`secondaryIconSource`	String	—	URL of an AVG to display as the secondary icon. Used when `secondaryIconName` isn't set.	Not supported	1.7.0
`secondaryText`	String	—	Secondary text to display.	Not supported	1.7.0
`singleRatingGraphic`	Any	—	The graphic to display to represent the rating. Used when `ratingSlotMode` is `single`. You can provide either a reference to an AVG or the URL of an image. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	Not supported	1.7.0
`singleRatingGraphicWidth`	Dimension	—	The width of the bounding box for the single graphic that represents the rating. Used when `ratingSlotMode` is `single`. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	Not supported	1.7.0
`tertiaryIconName`	String	—	Tertiary icon name. Set to the name of an icon in the Alexa Icon Library. You must also import the `alexa-icon` package into your document.	Not supported	1.7.0
`tertiaryIconSource`	String	—	URL of an AVG to display as the tertiary icon. Used when `tertiaryIconName` isn't set.	Not supported	1.7.0
`tertiaryText`	String	—	Tertiary text to display.	Not supported	1.7.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	Not supported	1.7.0
`type`	String	—	Always set to `AlexaCard`.	Not supported	1.7.0

AlexaCard example

The following example shows AlexaCard displayed within a horizontal Sequence component. When you tap a card, the header updates to show the ID of the card you tapped and Alexa sends a UserEvent with this information to the skill. To test the SendEvent command, copy this example to a skill.

APL Sequence

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023