Carousels

You can use structured data to make your rich results 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 results

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: Recipe, Course, Article.

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_dessert_recipes.html: 
ItemList
  itemListElement: [
    {
      @type: ListItem
      position: 1
      url: http://example.com/coffee_cake.html
    },
    {
      @type: ListItem
      position:2
      url: http://example.com/apple_pie.html,
    },
    ... more recipes ...
  ]
 Pseudocode for coffee_cake.html: 
@type: Recipe
name: Party Coffee Cake
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_dessert_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: Party Coffee Cake
        author: Mary Stone
        ... 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. You must include the required properties for your content to be eligible for display as a rich result. You can also include the recommended properties to add more information about your content, which could provide a better user experience.

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 at schema.org/ItemList.

Required properties
itemListElement

ListItem

List of items. All items must be of the same type. See ListItem 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 at schema.org/ListItem.

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"
    ], ... snip ...
  }
}
Required properties
item

Thing

Used for all-in-one-page lists only. This property is required for all-in-one-page lists. Do not include for summary pages. Populate this object with the following values, plus all the members of the specific structured data type being described:

  • item.name
  • item.url
  • 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.
item.name

Text

String name of the item, displayed in the rendered gallery. HTML formatting is ignored. This property is required for all-in-one-page lists. Do not include for summary pages.
item.url

URL

Fully-qualified URL + page anchor to this item on the page. This property is required for all-in-one-page lists. Do not include for summary pages. 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.
position

Integer

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

URL

Used for summary page lists only. This property is required for summary pages. Do not include for all-in-one-page lists. 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).

Send feedback about...

This page
Documentation feedback
Search
Search
Product feedback