Text List Item


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.


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


Was this page helpful?

Last updated: Dec 06, 2023