Carousel

A carousel is a list-like rich result that people can swipe through on mobile devices. It displays multiple cards from the same site (also known as a host carousel). To enable a carousel for your site, add Carousel structured data in combination with one of the following supported content types:

Here's how carousels can look in Google Search when you add Carousel markup in combination with a supported content type:

Examples of a recipe host carousel, a course host carousel, and a movie host
              carousel in Google Search

Add structured data

Structured data is a standardized format for providing information about a page and classifying the page content. If you’re new to structured data, you can learn more about how structured data works.

Here's an overview of how to add structured data to your site:

  1. Decide which page will contain the Carousel structured data. There are two options:
    • Summary page and multiple detail pages: The summary page has a short description of each item in the list, and each description points to a separate detail page that is focused entirely on one item. For example, a summary page that lists the best cookie recipes, and each description links out to the full recipe for each cookie.
    • A single, all-in-one-page list: A single page that contains all list information, including full text of each item. For example, a list of the top movies in 2020, all contained on one page.
  2. Add the required properties. For information about where to put structured data on the page, watch JSON-LD structured data: Where to insert on the page.
  3. Add the required and recommended properties for the specific content type that the Carousel is about:
  4. Follow the guidelines.

Summary page and multiple detail pages

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

Summary page

The summary 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).

Here's an example of what the summary page looks like:


<html>
  <head>
    <title>Best cookie recipes</title>
    <script type="application/ld+json">
    {
      "@context":"https://schema.org",
      "@type":"ItemList",
      "itemListElement":[
        {
          "@type":"ListItem",
          "position":1,
          "url":"http://example.com/peanut-butter-cookies.html"
        },
        {
          "@type":"ListItem",
          "position":2,
          "url":"http://example.com/triple-chocolate-chunk.html"
        },
        {
          "@type":"ListItem",
          "position":3,
          "url":"http://example.com/snickerdoodles.html"
        }
      ]
    }
    </script>
  </head>
  <body>
    <p>
      Here are the best cookie recipes of all time.
    </p>
    <h2>
      Peanut Butter Cookies
    </h2>
    <p>
      This <a href="https://example.com/peanut-butter-cookies.html">Peanut Butter Cookie recipe</a> is the tastiest one you'll find.
    </p>
    <h2>
      Triple Chocolate Chunk Cookies
    </h2>
    <p>
      This <a href="https://example.com/triple-chocolate-chunk.html">Triple Chocolate Chunk Cookies recipe</a> is the tastiest one you'll find.
    </p>
    <h2>
      Snickerdoodles
    </h2>
    <p>
      This <a href="https://example.com/snickerdoodles.html">Snickerdoodles recipe</a> is the tastiest one you'll find.
    </p>
  </body>
</html>

Details page

The details page defines the specific structured data type that the Carousel is about. For example, if the summary page is about the best cookie recipes, each detail page would contain Recipe structured data for a specific recipe.

Here's an example of what the detail pages look like:

Peanut butter cookies


<html>
  <head>
    <title>Peanut Butter Cookies</title>
    <script type="application/ld+json">
    {
      "@context": "https://schema.org/",
      "@type": "Recipe",
      "name": "Peanut Butter Cookies",
      "image": [
        "https://example.com/photos/1x1/photo.jpg",
        "https://example.com/photos/4x3/photo.jpg",
        "https://example.com/photos/16x9/photo.jpg"
      ],
      "author": {
        "@type": "Person",
        "name": "Wendy Darling"
      },
      "datePublished": "2018-03-10",
      "description": "This Peanut Butter Cookie recipe is everyone's favorite",
      "prepTime": "PT10M",
      "cookTime": "PT25M",
      "totalTime": "PT35M",
      "recipeCuisine": "French",
      "recipeCategory": "Cookies",
      "keywords": "peanut butter, cookies",
      "recipeYield": "24",
      "nutrition": {
        "@type": "NutritionInformation",
        "calories": "120 calories"
      },
      "aggregateRating": {
        "@type": "AggregateRating",
        "ratingValue": "5",
        "ratingCount": "18"
      },
      "recipeIngredient": [
        "2 cups of peanut butter",
        "1/3 cup of sugar"
      ],
      "recipeInstructions": [
        {
          "@type": "HowToStep",
          "text": "Mix together the peanut butter and sugar."
        },
        {
          "@type": "HowToStep",
          "text": "Roll cookie dough into small balls and place on a cookie sheet."
        },
        {
          "@type": "HowToStep",
          "text": "Bake for 25 minutes."
        }
      ],
      "video": {
        "@type": "VideoObject",
        "name": "How to Peanut Butter Cookies",
        "description": "This is how you make peanut butter cookies.",
        "thumbnailUrl": [
          "https://example.com/photos/1x1/photo.jpg",
          "https://example.com/photos/4x3/photo.jpg",
          "https://example.com/photos/16x9/photo.jpg"
         ],
        "contentUrl": "http://www.example.com/video123.mp4",
        "embedUrl": "http://www.example.com/videoplayer?video=123",
        "uploadDate": "2018-02-05T08:00:00+08:00",
        "duration": "PT1M33S",
        "interactionStatistic": {
          "@type": "InteractionCounter",
          "interactionType": { "@type": "http://schema.org/WatchAction" },
          "userInteractionCount": 2347
        },
        "expires": "2019-02-05T08:00:00+08:00"
       }
    }
    </script>
  </head>
  <body>
    <p>
      Here's how to make peanut butter cookies.
    </p>
    <ol>
      <li>Mix together the peanut butter and sugar.</li>
      <li>Roll cookie dough into small balls and place on a cookie sheet.</li>
      <li>Bake for 25 minutes.</li>
    </ol>
  </body>
</html>

Triple Chocolate Chunk Cookies


<html>
  <head>
    <title>Triple Chocolate Chunk Cookies</title>
    <script type="application/ld+json">
    {
      "@context": "https://schema.org/",
      "@type": "Recipe",
      "name": "Triple Chocolate Chunk Cookies",
      "image": [
        "https://example.com/photos/1x1/photo.jpg",
        "https://example.com/photos/4x3/photo.jpg",
        "https://example.com/photos/16x9/photo.jpg"
      ],
      "author": {
        "@type": "Person",
        "name": "Wendy Darling"
      },
      "datePublished": "2018-03-10",
      "description": "This Triple Chocolate Chunk Cookie recipe is everyone's favorite",
      "prepTime": "PT10M",
      "cookTime": "PT25M",
      "totalTime": "PT35M",
      "recipeCuisine": "French",
      "recipeCategory": "Cookies",
      "keywords": "chocolate, cookies",
      "recipeYield": "24",
      "nutrition": {
        "@type": "NutritionInformation",
        "calories": "120 calories"
      },
      "aggregateRating": {
        "@type": "AggregateRating",
        "ratingValue": "5",
        "ratingCount": "18"
      },
      "recipeIngredient": [
        "2 cups of melted chocolate",
        "1/3 cup of sugar"
      ],
      "recipeInstructions": [
        {
          "@type": "HowToStep",
          "text": "Mix together the chocolate and sugar."
        },
        {
          "@type": "HowToStep",
          "text": "Roll cookie dough into small balls and place on a cookie sheet."
        },
        {
          "@type": "HowToStep",
          "text": "Bake for 25 minutes."
        }
      ],
      "video": {
        "@type": "VideoObject",
        "name": "How to Triple Chocolate Chunk Cookies",
        "description": "This is how you make peanut butter cookies.",
        "thumbnailUrl": [
          "https://example.com/photos/1x1/photo.jpg",
          "https://example.com/photos/4x3/photo.jpg",
          "https://example.com/photos/16x9/photo.jpg"
         ],
        "contentUrl": "http://www.example.com/video123.mp4",
        "embedUrl": "http://www.example.com/videoplayer?video=123",
        "uploadDate": "2018-02-05T08:00:00+08:00",
        "duration": "PT1M33S",
        "interactionStatistic": {
          "@type": "InteractionCounter",
          "interactionType": { "@type": "http://schema.org/WatchAction" },
          "userInteractionCount": 2347
        },
        "expires": "2019-02-05T08:00:00+08:00"
       }
    }
    </script>
  </head>
  <body>
    <p>
      Here's how to make Triple Chocolate Chunk Cookies.
    </p>
    <ol>
      <li>Mix together the chocolate and sugar.</li>
      <li>Roll cookie dough into small balls and place on a cookie sheet.</li>
      <li>Bake for 25 minutes.</li>
    </ol>
  </body>
</html>

Snickerdoodles


<html>
  <head>
    <title>Snickerdoodles</title>
    <script type="application/ld+json">
    {
      "@context": "https://schema.org/",
      "@type": "Recipe",
      "name": "Snickerdoodles",
      "image": [
        "https://example.com/photos/1x1/photo.jpg",
        "https://example.com/photos/4x3/photo.jpg",
        "https://example.com/photos/16x9/photo.jpg"
      ],
      "author": {
        "@type": "Person",
        "name": "Wendy Darling"
      },
      "datePublished": "2018-03-10",
      "description": "This Snickerdoodles recipe is everyone's favorite",
      "prepTime": "PT10M",
      "cookTime": "PT25M",
      "totalTime": "PT35M",
      "recipeCuisine": "French",
      "recipeCategory": "Cookies",
      "keywords": "cinnamon sugar, cookies",
      "recipeYield": "24",
      "nutrition": {
        "@type": "NutritionInformation",
        "calories": "120 calories"
      },
      "aggregateRating": {
        "@type": "AggregateRating",
        "ratingValue": "5",
        "ratingCount": "18"
      },
      "recipeIngredient": [
        "2 cups of cinnamon",
        "1/3 cup of sugar"
      ],
      "recipeInstructions": [
        {
          "@type": "HowToStep",
          "text": "Mix together the cinnamon and sugar."
        },
        {
          "@type": "HowToStep",
          "text": "Roll cookie dough into small balls and place on a cookie sheet."
        },
        {
          "@type": "HowToStep",
          "text": "Bake for 25 minutes."
        }
      ],
      "video": {
        "@type": "VideoObject",
        "name": "How to Snickerdoodles",
        "description": "This is how you make snickerdoodles.",
        "thumbnailUrl": [
          "https://example.com/photos/1x1/photo.jpg",
          "https://example.com/photos/4x3/photo.jpg",
          "https://example.com/photos/16x9/photo.jpg"
         ],
        "contentUrl": "http://www.example.com/video123.mp4",
        "embedUrl": "http://www.example.com/videoplayer?video=123",
        "uploadDate": "2018-02-05T08:00:00+08:00",
        "duration": "PT1M33S",
        "interactionStatistic": {
          "@type": "InteractionCounter",
          "interactionType": { "@type": "http://schema.org/WatchAction" },
          "userInteractionCount": 2347
        },
        "expires": "2019-02-05T08:00:00+08:00"
       }
    }
    </script>
  </head>
  <body>
    <p>
      Here's how to make snickerdoodles.
    </p>
    <ol>
      <li>Mix together the cinnamon and sugar.</li>
      <li>Roll cookie dough into small balls and place on a cookie sheet.</li>
      <li>Bake for 25 minutes.</li>
    </ol>
  </body>
</html>

Single, all-in-one-page list

A single, all-in-one-page list contains all carousel information, including full text of each item. For example, a list of the top movies in 2020, all contained on one page. This page doesn't link out to other detail pages.

Here's an example of a single, all-in-one-page:


<html>
  <head>
    <title>The Best Movies from the Oscars - 2018</title>
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "ItemList",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": "1",
          "item": {
            "@type": "Movie",
            "url": "https://example.com/2019-best-picture-noms#a-star-is-born",
            "name": "A Star Is Born",
            "image": "https://example.com/photos/6x9/photo.jpg",
            "dateCreated": "2018-10-05",
            "director": {
                "@type": "Person",
                "name": "Bradley Cooper"
              },
            "review": {
              "@type": "Review",
              "reviewRating": {
                "@type": "Rating",
                "ratingValue": "5"
              },
              "author": {
                "@type": "Person",
                "name": "John D."
              },
              "reviewBody": "Heartbreaking, inpsiring, moving. Bradley Cooper is a triple threat."
              },
              "aggregateRating": {
                "@type": "AggregateRating",
                "ratingValue": "90",
                "bestRating": "100",
                "ratingCount": "19141"
              }
            }
          },
        {
          "@type": "ListItem",
          "position": "2",
          "item": {
            "@type": "Movie",
            "name": "Bohemian Rhapsody",
            "url": "https://example.com/2019-best-picture-noms#bohemian-rhapsody",
            "image": "https://example.com/photos/6x9/photo.jpg",
            "dateCreated": "2018-11-02",
            "director": {
                "@type": "Person",
                "name": "Bryan Singer"
              },
            "review": {
              "@type": "Review",
              "reviewRating": {
                "@type": "Rating",
                "ratingValue": "3"
              },
              "author": {
                "@type": "Person",
                "name": "Vin S."
              },
              "reviewBody": "Rami Malek's performance is overrated, at best."
              },
              "aggregateRating": {
                "@type": "AggregateRating",
                "ratingValue": "61",
                "bestRating": "100",
                "ratingCount": "21985"
              }
            }
          },
        {
          "@type": "ListItem",
          "position": "3",
          "item": {
            "@type": "Movie",
            "name": "Black Panther",
            "url": "https://example.com/2019-best-picture-noms#black-panther",
            "image": "https://example.com/photos/6x9/photo.jpg",
            "dateCreated": "2018-02-16",
            "director": {
                "@type": "Person",
                "name": "Ryan Coogler"
              },
            "review": {
              "@type": "Review",
              "reviewRating": {
                "@type": "Rating",
                "ratingValue": "2"
              },
              "author": {
                "@type": "Person",
                "name": "Trevor R."
              },
              "reviewBody": "I didn't like the lighting and CGI in this movie."
              },
              "aggregateRating": {
                "@type": "AggregateRating",
                "ratingValue": "96",
                "bestRating": "100",
                "ratingCount": "88211"
              }
            }
          }
      ]
    }
    </script>
  </head>
  <body>
  </body>
</html>

Guidelines

In addition to the General structured data guidelines, the following guidelines apply to Carousel structured data:

  • All items in the list must be of the same type. For example, if a list is about recipes, only include Recipe items. Don't mix different types.
  • Make sure that the Carousel structured data is complete and contains all the items that are listed on the page.
  • 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.

Validate and deploy structured data

  1. Validate your code using the Rich Results Test. For a summary page, there are some things you need to verify yourself:
    • Check that itemListElement contains two or more ListItem elements.
    • Make sure that all of the ListItem elements are the same type (for example, they are all about recipes).
    • Validate each URL that's mentioned in the list using the Rich Results Test. Each page in the list must contain valid structured data, per the documentation for the supported content type that the list is about: Recipe, Course, Restaurant, Movie.
  2. Deploy a few pages that include your structured data and use the URL Inspection tool to test how Google sees the page. Be sure that your page is accessible to Google and not blocked by a robots.txt file, the noindex tag, or login requirements. If the page looks okay, you can ask Google to recrawl your URLs.
  3. To keep Google informed of future changes, we recommend that you submit a sitemap. You can automate this with the Search Console Sitemap API.

Structured data type definitions

To specify a list, define an ItemList that contains at least two ListItems. You must include the required properties for your content to be eligible for display as a rich result.

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 an anchor on the page that's 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, include only the type, position, and url properties in the ListItem.
  • If this is an all-in-one-page list, include all the additional schema.org properties for the data type that it describes. The supported data types are:

The full definition of ListItem is available at schema.org/ListItem.

Summary pages

The following properties apply to summary pages:

Required properties
position

Integer

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

url

URL

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).

All-in-one pages

The following properties apply to all-in-one pages:

Required properties
item

Thing

An individual thing in a list. Populate this object with the following values, plus all the properties 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 the documents for your content type: Example: For a recipe, you would provide prepTime and image properties.
item.name

Text

The string name of the item. The item.name is displayed as the title of an individual item in the carousel. HTML formatting is ignored.

item.url

URL

The fully-qualified URL and 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.

position

Integer

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

Troubleshooting

If you're having trouble implementing structured data, here are some resources that may help you.