Index
Edit

Previews / List views

Sanity will often need to render a representation of a document, we call this a Preview. You can decide which fields should be used, and how, by implementing Preview. By default Sanity tries its best to guess which fields should be used for preview by introspecting the type's defined fields. For example, if your type has a field of type string named title, it will infer that this should be used as title when previewing values of this type.

Sanity offers two ways of customizing how documents are previewed:

  1. Specify preview options for the type in schema
  2. Implementing a custom preview component.

Specify preview options

If you want to specify which fields should be used for what, you can control this by adding a preview key to the type as defined in the schema. For example:

{
  name: 'movie',
  type: 'object',
  fields: [
    {
      title: 'Title',
      name: 'title',
      type: 'string'
    },
    {
      title: 'Release Date',
      name: 'releaseDate',
      type: 'date'
    }
  ],
  preview: {
    select: {
      title: 'title',
      subtitle: 'releaseDate'
    }
  }
}

Above, the preview.select object will inform the Sanity preview logic that movie.title should be used as title and movie.releaseDate should be used as subtitle.

This might be sufficient in many cases, but sometimes you want to reformat the selected values. Say releaseDate (e.g. 2016-04-25) is a bit hard on the eyes. All we really want is the year:

{
  name: 'movie',
  type: 'object',
  fields: [
    {
      title: 'Title',
      name: 'title',
      type: 'string'
    },
    {
      title: 'Release Date',
      name: 'releaseDate',
      type: 'date'
    }
  ],
  preview: {
    select: {
      title: 'title',
      date: 'releaseDate'
    },
    prepare(selection) {
      const {title, date} = selection
      return {
        title: title,
        subtitle: date.split('-')[0] // YYYY-MM-DD --> YYYY
      }
    }
  }
}

Above, title and releaseDate is selected. The result of this selection is passed to the prepare function, where you can transform the selection however you like (only keeping the year, in this case).

Pro tip: The select object is actually a data query, so you can follow relations etc in the select object. For example:

preview: {
  select: {
    title: 'title',
    director: 'director.name' // if the movie has a director, follow the relation and get the name
  },
  prepare(selection) {
    const {title, director} = selection
    return {
      title: title,
      subtitle: `Directed by: ${director ? director : 'unknown'}`
    }
  }
}

Custom preview component

If you want complete control of how the preview is rendered, you can also provide a React component that will be invoked whenever a value of a certain type should be previewed.

The component you'd like to use can be provided in preview config like this:

preview: {
  select: {
    title: 'title',
    director: 'director.name' // if the movie has a director, follow the relation and get the name
  },
  prepare(selection) {
    const {title, director} = selection
    return {
      title: title,
      subtitle: `Directed by: ${director ? director : 'unknown'}`
    }
  },
  component: MyPreviewComponent
}

This will pass the value to the preview component, using the selection from select. For a complete example, see the VideoEmbed preview and the actual preview component.

Previous: Hiding TypesNext: Previewing block content