Text List Item

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

The Alexa text list item responsive component (AlexaTextListItem) displays text, formatted to display within a list.

Compatibility

AlexaTextListItem is designed to work with the following viewport profiles:

The following widget viewport profiles in the alexa-viewport-profiles package:
- Widget Medium (@hubWidgetMedium)
All standard viewport profiles in the alexa-viewport-profiles package:
- All hub round profiles
- All hub landscape profiles
- All hub portrait profiles
- All mobile profiles
- All TV profiles

For details about viewport profiles, see Viewport Profiles.

Differences for widgets

When used within a widget, AlexaTextListItem displays a simplified list item to accommodate the small widget size.

List items display primary and secondary text and image thumbnails. List items don't display tertiary text, ratings, or item numbers.
You can't change the positioning of the secondary text in the list items.

Import the alexa-layouts package

To use AlexaTextListItem, import the alexa-layouts package.

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

Use the Other Versions option at the top of this page to see documentation for different versions of AlexaTextListItem. The table of parameters notes the version of alexa-layouts in which each parameter was added.

AlexaTextListItem parameters

The following table shows the parameters you can set on AlexaTextListItem. 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: {ordinal} {primaryText} {secondaryText} {tertiaryText} {ratingNumber} out of five stars from {ratingText}`	A string describing the text list item. Voice over reads this string when the user selects the item.	Medium	1.5.0
`componentSlot`	Component	—	An interactive responsive component to display at the end of the list item. Preferred options are `AlexaButton`, `AlexaRadioButton`, `AlexaSwitch`, or `AlexaCheckbox`.	Not supported	1.7.0
`emptyRatingGraphic`	Any	`empty`	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.2.0
`entities`	Array	—	Array of entity data to bind to this component.	Medium	1.2.0
`fullRatingGraphic`	Any	`full`	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.2.0
`halfRatingGraphic`	Any	`half`	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.2.0
`hideDivider`	Boolean	`false`	When `true`, hide the horizontal divider displayed below the list item.	Medium	1.1.0
`hideHorizontalMargin`	Boolean	`false`	When `true`, hide the default left and right padding.	Not supported	1.2.0
`hideOrdinal`	Boolean	`false`	When `true`, don't display a number next to the list time.	Not supported	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.	Medium	1.2.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.	Medium	1.2.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.	Medium	1.2.0
`imageThumbnailShadow`	Boolean	`true`	When `true`, display a drop shadow behind the image thumbnail.	Medium	1.3.0
`imageThumbnailSource`	String	—	URI for an image to display next to the list item as a thumbnail.	Medium	1.2.0
`layoutDirection`	String	`${environment.layoutDirection}`	Specifies the layout direction for the content. Set this property to either `LTR` (left-to-right) or `RTL` (right-to-left). This property doesn't inherit the `layoutDirection` from the component's parent container. Therefore, explicitly set this property when needed. For more details about support for right-to-left languages in the responsive components, see Support for Right-to-left Languages.	Medium	1.4.0
`primaryAction`	Command	—	The action to trigger when the user selects the list item. When not provided, the list item displays with a `disabled` state.	Medium	1.1.0
`primaryText`	String	—	Primary text to display for the list item.	Medium	1.1.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.2.0
`ratingNumber`	Number	-1	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.2.0
`ratingSlotMode`	String	—	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.2.0
`ratingText`	String	—	Text to display next to the rating. Ignored when `ratingNumber` is a negative number or omitted.	Not supported	1.2.0
`secondaryText`	String	—	Secondary text for each list item.	Medium	1.2.0
`secondaryTextPosition`	String	`bottom`	The position to display the `secondaryText`. Set to `top` or `bottom`. The `secondaryText` aligns to the start of the `primaryText`.	Not supported	1.2.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.2.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.2.0
`tertiaryText`	String	—	Tertiary text for each list item.	Not supported	1.2.0
`tertiaryTextPosition`	String	`end`	The position to display the `tertiaryText`. Set to `bottom` or `end`. When set to `end`, the `tertiaryText` displays above and after the `primaryText`. When set to `bottom`, the `tertiaryText` displays below the `primaryText` and is aligned with the start of the `primaryText`. When `componentSlot` is set, the component slot overrides tertiary text at `end` position.	Not supported	1.2.0
`textAlignmentCenter`	Boolean	`false`	When `true`, center the text. Applies to round hubs when `hideOrdinal` is `true`. Ignored for other viewports or when `hideOrdinal` is `false`.	Not supported	1.4.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	Medium	1.1.0
`touchForward`	Boolean	`false`	When `true`, assume the user is close enough to touch the screen (3-foot viewing distance) and format the list item with a smaller font size. When `false`, assume the user isn't close enough to touch the screen ("voice-forward") and use a larger font size.	Medium	1.2.0
`type`	String	—	Always set to `AlexaTextListItem`.	Medium	1.1.0

Text wrapping for a list item (maxLines)

The AlexaTextListItem component determines how many lines to show for the primaryText and secondaryText properties based on the viewport profile, image ratio, and contents of the item. For example, a larger viewport profile might show up to four lines for the primaryText, but a widget viewport shows three lines of text.

You can't change this setting.

AlexaTextListItem examples

The following example shows an AlexaTextListItem with primaryText, secondaryText, and tertiaryText.

The following example shows an AlexaTextListItem with a thumbnail graphic and a rating. Note that both the secondaryText and tertiaryText display on the bottom. Because this example doesn't set primaryAction, the list item displays as disabled.

The following example shows an AlexaTextListItem in a widget with primaryText and secondaryText.

{
  "type": "AlexaTextListItem",
  "primaryText": "This is the primary text. Longer text can wrap to 3 lines",
  "secondaryText": "This is the secondary text"
}

For an example of using AlexaTextListItem in a list, see AlexaTextList.

Last updated: Dec 13, 2022