docs

ItemList

The ItemList schema type describes an ordered or unordered collection of items. Google uses it to render carousel and list rich results — top-10 lists, ranked products, episode guides, and curated round-ups all benefit from this markup.

About ItemList

ItemList is one of the most flexible schema types. For ranked content (e.g. "Best laptops 2025"), set itemListOrder to ItemListOrderDescending and include explicit position values to lock the order. For navigation breadcrumbs, prefer the more specific BreadcrumbList type which Google treats differently in search results.

Fields

Field	Type	Required	Description
`name`	string	✓	The name of the list.
`description`	text	—	A description of the list.
`itemListOrder`	string	—	How items are ordered: ItemListOrderAscending, ItemListOrderDescending, or ItemListUnordered.
`numberOfItems`	number	—	Total number of items in the list.
`itemListElement[].position`	number	—	Order in the list (auto-set if not provided).
`itemListElement[].name`	string	—	The name of each list item.
`itemListElement[].url`	url	—	Link to the item.
`itemListElement[].image`	url	—	Image for the list item.
`itemListElement[].description`	text	—	Description of the list item.

Plugin Registration

sanity.config.ts

import { defineConfig } from 'sanity'
import { schemaOrgItemListPlugin } from 'sanity-plugin-seofields/schema'

export default defineConfig({
  plugins: [
    schemaOrgItemListPlugin(),
  ],
})

Schema Usage

Add theschemaOrgItemList field to any document schema:

schemas/roundup.ts

import { defineField, defineType } from 'sanity'

export default defineType({
  name: 'roundup',
  title: 'Roundup',
  type: 'document',
  fields: [
    defineField({
      name: 'schemaOrgItemList',
      title: 'ItemList Schema',
      type: 'schemaOrgItemList',
    }),
  ],
})

GROQ Query

GROQ query

*[_type == "roundup"][0]{
  schemaOrgItemList {
    name,
    description,
    itemListOrder,
    numberOfItems,
    itemListElement[]{
      position,
      name,
      url,
      image,
      description
    }
  }
}

Next.js Component

app/layout.tsx

import { ItemListSchema } from 'sanity-plugin-seofields/schema/next'

export default function Layout({ data }) {
  return <ItemListSchema data={data.schemaOrgItemList} />
}

JSON-LD Output

Generated JSON-LD

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "Top 5 React Frameworks of 2025",
  "description": "Our editor-curated ranking of the most popular React-based frameworks.",
  "itemListOrder": "https://schema.org/ItemListOrderDescending",
  "numberOfItems": 5,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Next.js",
      "url": "https://nextjs.org",
      "image": "https://example.com/img/nextjs.png",
      "description": "The React framework for the web."
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Remix",
      "url": "https://remix.run"
    }
  ]
}

Was this page helpful?