Carousels

You can use structured data to make your rich cards eligible for a list-like display called a carousel. Carousels typically appear only on mobile devices, and only for certain content types, as described below. If you use carousel markup for a content type not currently supported in carousel format, it is not an error; the information can still be displayed, but it not in a carousel.

In some cases, Google Search may display your rich result inside a carousel even if the page does not include structured data for a list: for example, a recipe might appear in a recipes carousel of results from many different websites.

Example

Here is a list of chicken recipes from a single website shown in a carousel:

Carousel of recipe rich cards

Guidelines

In addition to the standard structured data guidelines, the following guidelines apply to all list markup:

  • All items in the list must be of the same type, for example: Article or Recipe.
  • The text visible to the user must be similar to the information contained in the structured data on the page.
  • Items shown in list format will be shown in the order specified by the position property.
  • List format is currently supported for the following content types. This list is growing, so feel free to create a list for other types as they become supported: Recipe, Film, Course, Article, Recipe.

There are two ways to implement a list format for your structured data:

  • Summary page + multiple full details pages
  • A single, all-in-one-page list

Summary page + multiple full details pages

The summary page has a short description of each item in the list, and each description points to a separate details page that is focused entirely on one item.

Summary page Details page
Defines an ItemList, where each ListItem has only three properties: @type (set to "ListItem"), position (the position in the list), and url (the URL of a page with full details about that item). Defines a structured data element appropriate for that list type.
Pseudocode for best_pie_recipes.html:
ItemList
  itemListElement: [
    {
      @type: ListItem
      position: 1
      url: http://example.com/cherry_pie_recipe.html
    }, 
    {
      @type: ListItem
      position:2
      url: http://example.com/appple_pie_recipe.html,
    },
    ... more recipes ...
  ]
Pseudocode for cherry_pie_recipe.html:
@type: Recipe
name: George's Cherry Pie
author: George Smith
.... more properties ...

Sample code:

Sample code:

Single, all-in-one-page list

A single, all-in-one-page list hosts all list information, including full text of each item: for example, a gallery of recipes for various kinds of muffins, all contained on one page.

Single page
Defines an ItemList, where each element is a ListItem with the item property populated with the structured data for that schema.org element type (for example, Movie or Course). The page should contain user-visible text and an anchor to match each ListItem element.

Pseudocode for best_pie_recipes.html:

ItemList
  itemListElement: [
    {
      @type: ListItem
      position: 1
      item: {
        @type: recipe
        url: http://example.com/big_list_of_recipes#recipe_1
        name: George's Cherry Pie
        author: George Smith
        ... all other required Recipe type properties ...}
    },
    {
      @type: ListItem
      position: 2
      item: {
        @type: recipe
        url: http://example.com/big_list_of_recipes#recipe_2
        name: Martha's Apple Pie
        author: Martha Smith
        ... all other required Recipe type properties ...}
    },
    ... more recipes ...
  ]

 

Sample code:

Structured data type definitions

To specify a list, you must define an ItemList containing at least two ListItems.

ItemList

ItemList is the container item that holds all elements in the list. If used on a summary page, all URLs in the list must point to different pages on the same domain. If used on an all-in-one-page list, all URLs must point to the page hosting the list structured data.

The full definition of ItemList is available on schema.org.

Properties
@type

Required

Must be "ItemList".

itemListElement

ListItem, Required

List of items. All items must be of the same type. See ListItem below for details.

ListItem

ListItem contains details about an individual item in the list.

  • If this is a summary page, the ListItem should include only the type, position, and url properties.
  • If this is an all-in-one-page list, the ListItem should include all the additional schema.org properties for the data type that it describes (for example, Recipe or Course objects).

The full definition of ListItem is available on schema.org.

Example item in simple summary list (JSON-LD):

{
  "@type":"ListItem",
  "position":1,
  "url":"http://example.com/desserts/apple-pie"
}

Example item in all-in-one list (JSON-LD):

{
  "@type": "ListItem",
  "position": 1,
  "item": {
    "@type": "Recipe",
    "url": "http://example.com/desserts/pies/#apple-pie",
    "name": "Apple Pie",
    "image": "https://example.com/300px-Apple_pie.jpg",
     "aggregateRating": {
       "@type": "AggregateRating",
       "ratingValue": "6",
       "reviewCount": "32"
     },
     "recipeYield": "8 servings",
     "recipeIngredient": [
       "Pastry crust for bottom and top",
       "1/2 cup unsalted butter",
       "3 tablespoons all-purpose flour",
       "1/4 cup water",
       "1/4 cup white sugar",
       "1/2 cup brown sugar",
       "10 cups peeled, chopped green apples"
     ],
  }
}
Properties
@type

Required

Must be "ListItem"

position

Integer, Required

The item's position in the carousel. This is a 1-based number.

url

URL, Required for summary pages; Do not include for all-in-one-page lists

Used for summary page lists only. The canonical URL of the item detail page. All URLs in the list must be unique, but live on the same domain (the same domain or sub/super domain as the current page).

item

Thing, Required for all-in-one-page lists, Do not include for summary pages

Used for all-in-one-page lists only. Populate this object with the following values, plus all the members of the specific structured data type being described:

  • @type - The schema.org type name of the object being described. Example: "Recipe"
  • url - Fully-qualified URL + page anchor to this item on the page. The URL must be the current page, and you must include an HTML anchor (<a> tag or name or id value) in your page near the user-visible text. Example: "https://example.org/recipes/pies#apple_pie"
  • name - String name of the item, displayed in the rendered gallery. HTML formatting is ignored.
  • Any other properties required for this data type, as described in schema.org and the rules described in these documents for your content type (for example Article or Book). As an example, for a book in a list, you would provide bookFormat and isbn properties; for a recipe, you would provide prepTime and image properties.

Send feedback about...