Order your results

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

You can use the sortBy argument to sort your query results in a particular order. You can either do this in the plugin or directly in your GraphQL queries.

Ordering in the Plugin Options

Use this for ordering pagination of documents.

With the gatsby-source-prismic-graphql plugin you can specify the ordering of the results of a page type in the plugin options. The default setting is for this sortBy field is meta_lastPublicationDate_ASC; which is useful for pagination.

The following example shows 2 Custom Types with different ordering options: ascending & descending based on the date field.

Copy
pages: [{
  type: 'Article',
  match: '/:lang?/:uid',
  path: '/article',
  component: require.resolve('./src/templates/article.js'),
  sortBy: 'date_ASC',// optional,
  langs: ['en-us', 'es-es', 'is'],
}, {
  type: "Noticias",
  match: '/noticias/:uid',
  path: '/noticias',
  component: require.resolve('./src/templates/noticias.js'),
  sortBy: 'date_DESC',
  langs: ['es-es'],
}],

Here's a full Gatsby config example:

Copy
{
  resolve: '@prismicio/gatsby-source-prismic-graphql',
  options: {
    repositoryName: 'gatsby-source-prismic-test-site', // required
    defaultLang: 'en-us', // optional, but recommended
    accessToken: '...', // optional
    prismicRef: '...', // optional, default: master
    path: '/preview', // optional, default: /preview
    previews: true, // optional, default: false
    pages: [{ // optional
      type: 'Article', // TypeName from prismic
      match: '/article/:uid', // pages will be generated under this pattern
      previewPath: '/article', // optional path for unpublished documents
      component: require.resolve('./src/templates/article.js'),
      sortBy: 'date_ASC', // optional, default: meta_lastPublicationDate_ASC; useful for pagination
    }],
    extraPageFields: 'article_type', // optional, extends pages query to pass extra fields
    sharpKeys: [
      /image|photo|picture/, // (default)
      'profilepic',
    ],
  }
}

Ordering in the GraphQL Query

Use this for ordering a list of documents on a page.

The sortBy argument

The sortBy argument orders the results by a specific field. These fields will be separated into two categories: Meta fields that are metadata included in all documents and custom fields that are specific to each Custom Type.

You can provide a sortBy argument for the generated fields in the schema. Each field will provide you with either an ASC (ascending order) or DESC (descending order) option.

Generated arguments for all sorting options

All the arguments available for the sortBy operation are generated based on the Custom Type's fields and the available meta data. You can see all the available arguments by hitting CTRL+SPACE to get the autocomplete options in your GraphiQL explorer.

Sort by a content field

When performing a query for a given document type, you can sort the results by the fields in that type. You can use any of the following valid fields:

  • Rich Text
  • Title
  • Key Text
  • Select
  • Date
  • Timestamp
  • Number

For example, here is how to get all the "product" documents sorted by a number field that has the API ID of "price" from highest to lowest (descending order).

Copy
{
  prismic {
    allProducts(sortBy:price_DESC) {
      edges {
        node {
          title
          price
        }
      }
    }
  }
}

And here is an example that will sort all the documents of the type Author by a Key Text field with the API ID of "name" from A to Z (ascending order).

Copy
{
  prismic {
    allAuthors(sortBy:name_ASC) {
      edges {
        node {
          name
        }
      }
    }
  }
}

Note that only top-level fields can be used with the sortBy argument, meaning that, fields inside slices and/or groups are unavailable.

The sortBy argument cannot be used with custom API ID fields alone, they always have to be followed with either an ASC (ascending order) or DESC (descending order) option.

For example, if you were to use sortBy with a Rich Text field that has the API ID of "description", your argument options would be either: description_ASC or description_DESC.

Sort by publication date

It is possible to sort by first and last publication dates in either ascending or descending order for either.

First publication date

To sort by first publication date, simply use the sortBy argument with either meta_firstPublicationDate_ASC or meta_firstPublicationDate_DESC. This can be applied to any query.

Here is an example on how to get all "blog_post" documents sorted by first publication date from newest to oldest (descending order).

Copy
{
  prismic {
    allBlog_posts(sortBy:meta_firstPublicationDate_DESC) {
      edges {
        node {
          title
          _meta {
            firstPublicationDate
          }
        }
      }
    }
  }
}

Last publication date

In order to sort by last publication date, simply use the sortBy argument with either meta_lastPublicationDate_ASC or meta_lastPublicationDate_DESC. This can be applied to any query.

Here is an example on how to get all "blog_post" documents sorted by last publication date from oldest to newest (ascending order).

Copy
{
  prismic {
    allBlog_posts(sortBy:meta_lastPublicationDate_ASC) {
      edges {
        node {
          title
          _meta {
            lastPublicationDate
          }
        }
      }
    }
  }
}