# ItemList in Schema.org: Markup for Lists

> What ItemList is in Schema.org, how ListItem orders it, which Google carousels use it with products and how to review the markup on your category pages.

URL: https://clione.ai/glossary/itemlist/
Lang: en

A [category page](/glossary/category-page/), a "best sellers" list or a guide to the ten best products for something all have one thing in common: they are lists. ItemList is the [Schema.org](/glossary/schema-org/) type that describes them in the page's [structured data](/glossary/structured-data/). It should not be confused with HTML lists, the bulleted kind, which the vocabulary itself sets apart because they are often used only for layout.[^schema-itemlist] It matters to you because categories are the pages of a store that most often go without markup, because ItemList is the type that fits them and because it is easy to expect more from it than Google does with it.

## How it works

A list is described with three properties of ItemList's own:[^schema-itemlist]

- **`itemListElement`**, the items. They can be plain strings ("Peter", "Paul", "Mary"), entities already described or ListItem nodes. Schema.org recommends strings for lists of words, entities for a simple, unordered list, and ListItem for ordered lists or when the same item might appear in different places in different lists.
- **`itemListOrder`**, the type of ordering: ascending, descending or unordered.
- **`numberOfItems`**, how many items the list has. If the page shows only part of it, as on a paginated category, **the number is that of the whole list**.

The vocabulary adds a warning that changes how the markup is written: **the order of the items in the code is not enough to indicate the order of the list**. That is what ListItem is for, with its `position` property.[^schema-itemlist] Each ListItem carries the position, the item itself (`item`) and, if needed, links to the previous and the next (`previousItem` and `nextItem`).[^schema-listitem]

ItemList has a subtype that almost every store already publishes without knowing it: BreadcrumbList, the one for [breadcrumbs](/glossary/breadcrumbs/), which Schema.org defines as an ItemList made up of a chain of linked pages.[^schema-breadcrumblist] Schema.org estimates that ItemList is used by between one and ten million domains, with data from Google's index of August 2026.[^schema-itemlist]

## What Google does with a marked-up list

Google uses ItemList for one of its [rich results](/glossary/rich-results/): **the carousel**, a row of cards from a single site that slides horizontally. It has two separate documents, and it helps not to mix them up.

The general carousel combines ItemList with one of four kinds of content: courses, movies, recipes or restaurants. It supports two page shapes: a summary page, where each ListItem carries only `@type`, `position` and `url`, and each URL points to a different page on the same domain; or a page that contains everything, where the URLs point to anchors on the page itself. It asks for at least two ListItems, all of the same type.[^google-carousel] **Products are not on that list.**

Products are in the second: **a beta carousel** that combines ItemList with [Product](/glossary/product-schema/), with local businesses or with events, and that can show the price, the rating and the images on each card. It exists only in the countries of the European Economic Area, in Turkey and in South Africa, and in Turkey it does not cover products. For product queries in the countries of the comparison shopping services (CSS) program, the documentation refers you to start with that program.[^google-carousels-beta] The conditions it sets, according to its version of September 11, 2026:[^google-carousels-beta]

- The markup goes on a summary or category page with **at least three** items, which links to other pages on the same site. A page that contains everything does not qualify.
- All the items the page shows are marked up. On a paginated category, each page carries its own ItemList with what it shows; with infinite scroll, what loads at the start.
- Each item needs `name`, `image` and `url`. For a product, `offers` with `price` and `priceCurrency` is recommended, and **if the currency is missing, Google assumes it is dollars**.
- The order of the markup is the order of the cards.

And one thing ItemList does not do: turn a category into a [product page](/glossary/product-page/). Google's product results only accept pages centered on a single product (or on variants of it), and Google recommends marking up product pages, not pages that list products or a category.[^google-merchant-listing]

## On a store

**Fictional example.** The first page of the "Linen shirts" category of Calella, an invented store, with 14 shirts spread over five pages of three. The block, trimmed to two items:

```json
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "numberOfItems": 14,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "Product",
        "name": "Calella linen shirt, blue",
        "image": "https://www.example.com/img/calella-blue.jpg",
        "url": "https://www.example.com/calella-linen-shirt",
        "offers": { "@type": "Offer", "price": "39.90", "priceCurrency": "USD" }
      }
    },
    {
      "@type": "ListItem",
      "position": 2,
      "item": {
        "@type": "Product",
        "name": "Calella linen shirt, white",
        "image": "https://www.example.com/img/calella-white.jpg",
        "url": "https://www.example.com/calella-linen-shirt-white",
        "offers": { "@type": "Offer", "price": "39.90", "priceCurrency": "USD" }
      }
    }
  ]
}
```

It reads like this. `numberOfItems` says 14 even though the page shows three, because it counts the whole list. Each ListItem has its `position`, and each product has the three properties the beta carousel requires and an [Offer](/glossary/offer-schema/) with the currency written out. The URLs lead to the product pages, on the same domain. Page 2 would carry its own block with its three shirts.

To see what a stock theme ships, you can read its templates. Cornerstone, BigCommerce's default theme, released its version 6.22.0 on September 21, 2026: in it, the [JSON-LD](/glossary/json-ld/) block for Product goes on the product page and the one for BreadcrumbList in the breadcrumbs, and **no template includes ItemList**.[^cornerstone-repo] On a store with that theme, the category only describes where it is, not what it contains.


Believing that adding ItemList to a category is enough to appear in a Google carousel. For products, the only carousel that supports it is in beta and only in the European Economic Area and South Africa, asks for at least three items with name, image and URL, and Google may change its requirements while it remains in beta.[^google-carousels-beta] Outside those countries, a category well marked up with ItemList describes the page, but there is no product rich result to trigger.[^google-carousel]


## How to check it

1. **Open the page source of a category** and search for `ItemList`. If it does not appear, see what is there: often it is just the breadcrumbs.
2. **Count the items in the markup and the products you see.** They should match: Google asks you to mark up everything the page shows, and on page 2, what is on page 2.[^google-carousels-beta]
3. **Go over each ListItem**: a `position` that starts at 1 and does not repeat, and a `url` that leads to a product page on your domain.[^schema-itemlist][^google-carousels-beta]
4. **Look at each product's price**: `price` with a decimal point and `priceCurrency` set to the currency you charge in (USD in the example). Without a currency, Google assumes dollars.[^google-carousels-beta]
5. **Check that the category does not carry a Product block as if it were a product page.** Product results are for single-product pages.[^google-merchant-listing]

## Related concept: breadcrumbs (BreadcrumbList)

Breadcrumbs and the product list are the two lists a category carries, and both are marked up with the ItemList family. But they say different things. BreadcrumbList is a chain of linked pages that usually ends at the current page, with the home page or the section at the start and `position` to rebuild the order.[^schema-breadcrumblist] **The breadcrumbs say where the page is; the category's ItemList says what it contains.** A category can, and usually should, carry both.

To keep going, the [structured data reading path](/learn/structured-data/) puts the rest of the terms in order, and the [PLP](/glossary/plp/) entry explains what else a listing page needs: pagination, filters and what gets indexed.