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:
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
orRecipe
. - 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 |
List of items. All items must be of the same type. See |
ListItem
ListItem
contains details about an individual item in the list.
- If this is a summary page, the
ListItem
should include only thetype
,position
, andurl
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
orCourse
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
|
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
|
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
|
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 ( |
position
|
The item's position in the carousel. This is a 1-based number. |
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). |