Visual components List

List

Lists are optimized for allowing users to select one of many items when those items are most easily differentiated by their title. Users can select an item by either saying its title or tapping it.

Example Expand and collapse content An arrow that points down when collapsed and points up when expanded.

Here’s an example of what a list looks like when all required and optional fields are completed.

This example list card would be presented to a user shopping for flowers. The list title is Types of Daisies. It features three list items, and each item provides details about a particular bouquet of daisies. Every list item includes an image, primary text, and secondary text. The primary text states the type of daisy, and the secondary text details the number of flowers included and the price of the bouquet.

Requirements Expand and collapse content An arrow that points down when collapsed and points up when expanded.

This visual component currently supports customization.

Field name

Required?

Restrictions/Customizations

List title

No

Customizable font family and color.

Max 1 line recommended.

The card height collapses if no title is specified.

Primary text

Yes

Each item’s title must be unique (to support voice selection).

Plain text. Fixed font and size.

Max 1 line. Additional characters will be truncated with an ellipsis.

Secondary text

Also called body or formatted text.

No

Plain text. Fixed font and size.

Max 2 lines. Additional characters will be truncated with an ellipsis.

Item image

No

Images appear along the right.

Customizable image shape (angled or rounded corners).

Card background

No

Customizable image or color.

Number of items

Maximum: 30

Minimum: 1

Interactivity

  • Swipe: Slide the list card to reveal different list items.
  • Tap: When users tap a list item, the item’s title is accepted as the user input, starting the next turn in the dialog.
  • Voice/Keyboard: Replying with the item title is the same as selecting that item.

Guidance Expand and collapse content An arrow that points down when collapsed and points up when expanded.

Lists are mostly used for browsing and selecting among titles. Though you can have as few as 1 and as many as 30 list items, we recommend that you use between 2 and 10.

Use lists to help the user select from content that:

  • can be most meaningfully browsed via scanning short titles or descriptions (e.g., song titles, contact names, event names, session topics)
  • the user may have to scan and compare while browsing (e.g. stock prices)

Use titles that are unique and conversation friendly.

Users will be able to say the item’s title to select it, so make sure they’re easy to say, and uniquely identify each item.

Persona: Geek num (fake game). User input: 42. Spoken prompt: Alright, here are a few things you can learn, like its relation to math and prime numbers. Which one sounds interesting? Display prompt: Here are a few things you can learn. Which one sounds interesting? Visual: Rich list card showing three items: Math and prime numbers, Ancient Egyptian religion, and 42 recipes with 42 ingredients. Each item includes primary text, secondary text, and an image. Chips: Another number, Never mind.

Do.

Each item title should be as short as possible while staying distinct from the other items.

Persona: Geek num (fake game). User input: 42. Spoken prompt: Alright, here are a few things you can learn, like its relation to math and prime numbers. Which one sounds interesting? Display prompt: Here are a few things you can learn. Which one sounds interesting? Visual: Rich list card showing three items: 42 and its relation to math and prime numbers, 42 and its relation to ancient Egyptian religion, and 42 and its relation to recipes with 42 ingredients. Each item includes primary text, secondary text, and an image. Chips: Another number, Never mind.

Don’t.

Don’t repeat words or phrases across titles, e.g., “42 and its relation to…”. They don’t help uniquely identify the item, and the title will be too long to fit on the screen.

Keep descriptions concise by only including helpful, relevant information.

Space is limited, so front-load the information by giving users the most important information first.

Persona: Geek num (fake game). User input: 42. Spoken prompt: Alright, here are a few things you can learn, like its relation to math and prime numbers. Which one sounds interesting? Display prompt: Here are a few things you can learn. Which one sounds interesting? Visual: Rich list card titled Things to learn about, showing three items. Item 1 primary text: Math and prime numbers. Secondary text: 42 is an abundant number because the sum of its proper divisors, 54, is greater…(text cuts off). Item 2 primary text: Ancient Egyptian religion. Secondary text: 42 gods who ruled on the fate of the dead in the afterworld. Throughout the underworld…(text cuts off). Item 3 primary text: 42 recipes with 42 ingredients. Secondary text: Here’s a beautifully simple recipe that’s full of flavor! All you need is some ginger and…(text cuts off). Chips: Another number, Never mind.

Do.

List item descriptions should only contain information that differentiates them from each other and is relevant within the context of the user’s request of your Action.

Persona: Geek num (fake game). User input: 42. Spoken prompt: Alright, here are a few things you can learn, like its relation to math and prime numbers. Which one sounds interesting? Display prompt: Here are a few things you can learn. Which one sounds interesting? Visual: Rich list card titled Things to learn about, showing three items. Item 1 primary text: Math and prime numbers. Secondary text: Prime numbers can only be divided by themselves and 1. An abundant number…(text cuts off). Item 2 primary text: Ancient Egyptian religion. Secondary text: Ancient Egyptians worshiped many gods, some of whom have been compared…(text cuts off). Item 3 primary text: 42 recipes with 42 ingredients. Secondary text: A recipe is a list of ingredients and instructions that guides you through…(text cuts off). Chips: Another number, Never mind.

Don’t.

Avoid presenting irrelevant information in your list item descriptions; this takes valuable space away from information the user actually needs to make a choice.

If your list only has 2 items, consider whether a simple either/or question is sufficient to help the user make their decision.

It takes users time to visually scan everything on the screen, so make sure the content adds value.

Persona: Sekai (fake shoe store). User input: I’m looking for sneakers. Spoken prompt: Sneakers, sure. Do you want lace-up or slip-on shoes? Display prompt: Do you want lace-up or slip-on sneakers? Chips: Lace-up, slip-on, both.

Do.

If you’re only presenting two options, simply asking the question may be the best way to help the user make a decision.

Persona: Sekai (fake shoe store). User input: I’m looking for sneakers. Spoken prompt: Sneakers, sure. Do you want lace-up or slip-on shoes? Display prompt: Do you want lace-up or slip-on sneakers? Visual: Simple list card titled Shoe types, showing two items: Lace-up and slip-on. Chips: Lace-up, slip-on, both.

Don’t.

In this case, visuals aren’t necessary to present the important information. Chips will help the user respond if they need suggestions.

Avoid lists of 1 item.

If there’s only 1 option, then there’s no need to present a list for the user to choose from.

Persona: Sekai (fake shoe store). User input: Get me a size 10. Spoken prompt: There’s only 1 style left in size 10. Do you want to add it to your cart? Display prompt: There’s only 1 left. Do you want to add it to your cart? Visual: Basic card titled Lace-up boots, size 10. This card includes an image and details about the shoes available. Chips: Add to cart, save for later, hiking shoes.

Do.

Instead of a 1-item list, present the user with more information on the 1 option that’s available to them.

Persona: Sekai (fake shoe store). User input: Get me a size 10. Spoken prompt: Here’s what’s available in size 10. Which do you want? Display prompt: Here’s what’s available in size 10. Which do you want? Visual: List card titled Available shoes, showing only 1 item: Lace-up boots in size 10 for 199 dollars. Chips: None of those, hiking shoes, running shoes.

Don’t.

Don’t make the user choose when there’s only 1 option.