Get a peek at our latest innovations at Sanity Product Day on Dec 8th →

Documents Pane

v3 Ready

By Victoria Bergquist & Simeon Griggs

Display the results of any GROQ Query inside a View Pane


This is a Sanity Studio v3 plugin. For the v2 version, please refer to the v2-branch.

Displays the results of a GROQ query in a View Pane. With the ability to use field values in the current document as query parameters.

Incoming References


npm install --save sanity-plugin-documents-pane@studio-v3


yarn add sanity-plugin-documents-pane@studio-v3

This plugin is designed to be used as a Component inside of a View.

The example below illustrates using the current Document being used to query for all published documents that reference it.

// ./src/deskStructure.js
import DocumentsPane from 'sanity-plugin-documents-pane'

// ...all other list items

    query: `*[!(_id in path("drafts.**")) && references($id)]`,
    params: {id: `_id`},
  .title('Incoming References')

The .options() configuration works as follows:

  • query (string, required) A string defining the entire GROQ query that will select documents to list.
  • params (object or function, optional)
    • Object: a dot-notated string from the document object to a field, to use as variables in the query.
    • Function: a function that receives the various displayed, draft, and published versions of the document, and returns an object of query parameters. Return null if the parameters cannot be resolved.
  • useDraft (bool, optional, default: false) When populating the params values, it will use the published version of the document by default. Not permitted if using a function for params as the function will determine which version of the document to use.
  • debug (bool, optional, default: false) In case of an error or the query returning no documents, setting to true will display the query and params that were used.
  • initialValueTemplates (function, optional) A function that receives the various displayed, draft, and published versions of the document, and returns a list of initial value templates. These will be used to define buttons at the top of the list so users can create new related documents.

Resolving query parameters with a function and providing initial value templates

Providing a function for params allows us to modify values from the current document, for example to list references to a draft document. Providing a function for the initialValueTemplates option allows us to determine which buttons to show and what parameters will be used for the new document.

const options = {
  query: `*[_type=="post" && author._ref == $id]`,
  params: ({document}) => {
    // references will never point to a draft ID, so extract the regular ID
    const id = document.displayed._id?.replace('drafts.', '')

    // we don't have to worry about undefined parameters,
    // as the plugin will handle them and show an appropriate message
    return {id}
  initialValueTemplates: ({document}) => {
    const templates = []

    // references must point to a non-draft ID, so if using the ID in the template,
    // be sure it doesn't start with `drafts.`
    const id = document?.displayed?._id.replace('drafts.', '')
    const name = document?.displayed?.name || 'author'

    if (id) {
        // the name of the schema type that should be created (required)
        schemaType: 'post',
        // the title that should appear on the button - we can customize it (required)
        title: `New post by ${name}`,
        // the name of the template that should be used (optional)
        template: 'postWithAuthor',
        // values for parameters that can be passed to the template referenced above (optional)
        parameters: {
          authorId: id,

      // we could push more templates if needed.

    // must always return a list, even if empty
    return templates


This plugin is based on Incoming References originally written by Victoria Bergquist.


MIT-licensed. See LICENSE.

Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.

Release new version

Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.

Studio Version

This plugin is available for Studio v3 and Studio v2.What are studio versions and which do I choose?


Categorized in

Other plugins by authors

Orderable Document List
- has 27 likes

Official(made by Sanity team)

Drag-and-drop Document Ordering without leaving the Editing surface

Simeon Griggs
Go to Orderable Document List

Mux input
- has 7 likes

v3 Ready

Upload videos to Mux directly from the studio.

Go to Mux input

Hotspot array

Official(made by Sanity team)
v3 Ready

Associate arrays with hotspots on any image

Go to Hotspot array