👋 Next.js Conf 2024: Come build, party, run, and connect with us! See all events

Sort Orders

When displaying a collection of documents it's useful to be able to sort the collection by different fields. You do this by specifying an orderings property in the schema:

{
  name: 'movie',
  type: 'document',
  fields: [
    {
      title: 'Title',
      name: 'title',
      type: 'string'
    },
    {
      title: 'Release Date',
      name: 'releaseDate',
      type: 'date'
    },
    {
      title: 'Popularity',
      name: 'popularity',
      type: 'number'
    }
  ],
  orderings: [
    {
      title: 'Release Date, New',
      name: 'releaseDateDesc',
      by: [
        {field: 'releaseDate', direction: 'desc'}
      ]
    },
    {
      title: 'Release Date, Old',
      name: 'releaseDateAsc',
      by: [
        {field: 'releaseDate', direction: 'asc'}
      ]
    },
    {
      title: 'Popularity',
      name: 'popularityDesc',
      by: [
        {field: 'popularity', direction: 'desc'}
      ]
    }
  ]
}

The orderings above define a list of possible ways to order a collection of movies. To the user these appear as options in the Studio when the movies are listed, with each object in orderings being its own sort option (one can sort by Release Date, New OR Release Date, Old OR Popularity).

Default sort orders

If no sort orders are defined, Sanity will do its best to guess what fields would make sense to sort by.

When no ordering is specified:

  • If the document type has string fields named title, name, label, heading, header, caption or description, we enable options to order by all of these.
  • If your type has no fields named any of the above, we will generate ordering configs for all fields of primitive types, that is fields of type string, number, or boolean.

If you specify your own ordering, we skip the default heuristics above.

Was this article helpful?