What is ItemList structured data, and how do you use it?
guide // , 5 min read, by Darthwares
ItemList structured data is a Schema.org format that defines a machine-readable list of items on a web page. You use it by adding an ItemList container to your page markup and populating its itemListElement property with strings, entities, or ListItem objects. Schema.org defines ItemList for lists of any sort, such as top song or movie collections. Unlike standard HTML lists used for formatting, ItemList conveys explicit structure and item ordering to search engine crawlers.
On this page // 6 sections
The short version
- ItemList is a container schema type that organizes items on a web page for search engines.
- The order of elements in HTML source is not enough to define sequence, so you must use ListItem with a position property.
- Search engines like Google use ItemList on summary pages to present list-like rich results and mobile host carousels.
- All items in a carousel list must share the same entity type and appear on a page with at least three entities.
What is ItemList structured data?
ItemList is a Schema.org structured data container that holds all elements in a list. Schema.org defines an ItemList as a list of items of any sort, such as a list of Top 10 Movies About Weathermen or Top 100 Party Songs. Google documents that ItemList serves as the primary container item holding every element present in the collection.
Schema.org explicitly distinguishes ItemList structured data from standard HTML list elements. HTML lists like unordered or ordered tags are often used only for visual layout and formatting. Structured data provides explicit semantic metadata that search engine crawlers can read independently of visual presentation.
How do you structure list items with itemListElement?
The primary property inside an ItemList is itemListElement. Schema.org allows you to populate itemListElement using simple strings, existing entities, or ListItem objects. Text values work best when elements in the list are plain strings, such as simple text names. Existing entities work best for a simple, unordered list of existing data objects in your system.
When building ordered lists, Schema.org specifies using the ListItem type. A ListItem represents a list item, such as a step in a checklist, a how-to description, or an entry in a data feed like an artist in a list of artists. Using ListItem is recommended when providing additional context about an element or when the same item appears in different positions across different lists.
Schema.org notes that the physical order of elements in HTML markup is not sufficient for indicating the order of elements. To define order explicitly, you must use ListItem with a position property that indicates the position of an item in a series or sequence of items. A ListItem can also include a link to the ListItem that follows the current one or a link to the ListItem that precedes the current one.
How does ItemList enable carousels in search results?
Google uses ItemList structured data to build carousels, which are list-like rich results that users can swipe or scroll through horizontally on mobile devices. Google explains that host carousels display multiple cards or tiles from the same site. On mobile search results, each tile in a carousel can display summary details from your site, such as prices, ratings, and images for entities featured on the page.
To qualify for a carousel, Google specifies that you must pick a single summary or category page that contains information about at least three entities. The summary page includes a short description of each item in the list and links out to separate detail pages on your site focused entirely on single items. Alternatively, a site can use a single, all-in-one-page list that hosts all list information, including full text for each item.
Google requires that all items in a carousel list must be of the same type. You must mark up all items present on the summary or category page, ensuring the structured data is complete. Google search results display items in list format in the order specified by the position property of each item. For paginated category lists, Google documents adding an ItemList to each subsequent page to cover the specific entities listed on that page.
How do you use ItemList for recipes and movies?
Google documents specific implementations of ItemList structured data for collections such as recipes and movies. For recipe content, Google specifies using Recipe structured data for content about preparing a particular dish. To summarize a list of recipes, you can provide ItemList structured data either separately or together with Recipe structured data, provided your site hosts a summary page listing all recipes in the collection.
Movie collections also utilize ItemList markup so users can explore movie lists on Google Search in new ways. Details about movies can include titles, directors, and images, but Google notes that movie carousels are only available on mobile devices. Just like recipe collections, a movie summary page provides a short description of each item in the list and links to a dedicated detail page for each item.
How do you troubleshoot ItemList structured data?
When implementing ItemList structured data, validation failures usually stem from missing position properties or incomplete list coverage. You can verify your implementation by running a step-by-step diagnostic process.
- 01Verify that your markup is placed on a summary or category page that lists at least three entities of the same type.
- 02Inspect every item entry in your markup to confirm that a numeric position property is assigned to every ListItem.
- 03Compare the marked-up items against the visible page content to confirm all visible items are included without missing elements across paginated pages.
| Symptom | Diagnostic check | Required fix |
|---|---|---|
| Items display in wrong sequence in search results | Check if item sequence relies only on HTML markup order instead of explicit property values | Add a ListItem object with an explicit position property for every element |
| Carousel rich result fails to trigger on summary page | Check if page contains fewer than three entities or has mixed item types | Ensure at least three entities of identical type are marked up on the summary page |
| Incomplete items on paginated category lists | Check if subsequent pages omit ItemList markup or omit entities on those pages | Add an ItemList to each subsequent page covering all entities listed on that page |
Common questions
Can you rely on HTML element order to set sequence in an ItemList?
No. Schema.org notes that the order of elements in HTML mark-up is not sufficient for indicating order. You must use ListItem with a position property to set item sequence.
What is the difference between HTML lists and ItemList structured data?
Schema.org explains that HTML lists are often used only for visual formatting, whereas ItemList structured data provides explicit, machine-readable list metadata to search engines.
Must all items in an ItemList carousel be the same entity type?
Yes. Google search guidelines require that all items in a carousel list must be of the same entity type.
Are movie carousels displayed on desktop search results?
No. Google explicitly documents that the movie carousel rich result is only available on mobile devices.
Primary sources and further reading
This article was researched and written by an AI model and published automatically. It was written from sentences that were checked to appear on the pages below, but a person has not reviewed the text. If something is wrong, tell us at chibivikramathithan@darthwares.com and we will correct it.