Structure Builder API Reference

This is the complete reference documentation for Structure Builder. This API lets you configure how the Sanity Studio's Structure tool organizes lists, documents, views, menus, and initial value templates.

The Structure Builder API is designed as a collection of methods that can be chained and passed in as arguments/parameters. To learn about the central concepts of Structure Builder, go to the introduction article and dive deeper into the API in the TypeScript reference documentation.

You can build custom structures by passing the structure to the structure tool configuration. To do this, define the structure resolver function, which receives the Structure Builder instance, by convention referred to as S, as its first argument, and a context object as its second.

// sanity.config.js

import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {schemaTypes} from './schema'

export default defineConfig({
  name: 'default',
  title: 'My Cool Project',
  projectId: 'my-project-id',
  dataset: 'production',
  plugins: [
    structureTool({
      structure: (S, context) => {
        console.log(context) // returns { currentUser, dataset, projectId, schema, getClient, documentStore }
        return S.documentTypeList('post')
      },
    })
  ],
  schema: schemaTypes
})

Where you define your structure is up to you - you could define it inline (as in the above example), or you could place it in a separate file and import/use it in your structure tool config:

// src/structure.js

export const structure = (S) => S.documentTypeList('post')

// sanity.config.ts
import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { structure } from './src/deskStructure'

export default defineConfig({
  // ...
  plugins: [
    structureTool({
      structure
    })
  ]
})

In the Structure Builder API, you'll find “convenience methods.” We recommend using these unless you want more fine-grained control.

These methods define how lists and list items appear in the collapsible panes within the Studio’s structure tool. There are methods you can consider as “primitives” and methods that take a document schema type and automatically configure menus, initial value templates, and similar from the schema configuration.

list():List

A primitive for defining the list content of the collapsible pane, including its title and representation in the URL bar. Typically used when you want to group different list items within a pane.

documentTypeList(schemaType):DocumentList

Convenience method for documentList(). Returns a list node for the specified document type with its configuration for list items, menus, initial value templates, and views.

See the methods summary for documentList

// src/structure.js (.ts)

// Exports a list of documents with the schema type “post”
export const structure = (S) => S.documentTypeList('post')

documentList():DocumentList

A variant of the list type is made specifically for displaying a list of documents. It lets you define which documents to list by using a GROQ filter expression (filter) plus optional parameters (params). Note that this list type does not have an items() method - if you want to use specific list items, use the list() method instead.

Shares methods from list

// ./structure.js (.ts)

export const structure = (S) =>
  S.list()
    .title('Content')
    .items([
      S.listItem()
        .title('Future projects')
        .schemaType('sampleProject')
        .child(
          S.documentList()
            .title('Future projects')
            .filter('_type == "sampleProject" && publishedAt > now()')
        )
      ])

// src/structure.js

export const structure = (S) => S.documentTypeList('sampleProject')
  S.list()
    .title('Content')
    .items([
      S.listItem('category')
        .title('Projects by category')
        .child(
          S.documentList()
            .title('Projects by category')
            .schemaType('sampleProject') // Because we want menu items for “sampleProjects”
            .filter('_type == "category"')
            .child(id => // Returns the id for the selected category document
              S.documentList()
                .title('Projects by category')
                .schemaType('sampleProject')
                .filter('_type == "sampleProject" && $id in categories[]._ref')
                .params({id}) // use the id in the filter to return sampleProjects that has a reference to the category
            )
        )
      ])

export const structure = (S) =>
  S.list()
    .title('Content')
    .items([
      /* list item(s) goes here */
    ])

listItem():ListItem

A primitive for defining a list item within a list in a collapsible pane. Usually used within the array of S.list().items([/* here */]).

By using the child method on the item, you can control what opens in the next pane when you interact with a listItem. If not defined, it will use the parents' child resolver to determine the next pane.

documentListItem():DocumentListItem

Convenience method for returning a list item representing a document.

Prefer this over a regular listItem when manually building a list of items representing documents.

Shares the same methods as listItem.

documentTypeListItem(schemaType):ListItem

Convenience method for returning a list item representing a document type. In other words, if you want a list item that opens a list of documents of a specific type when clicked, use this. It will automatically configure the title, icon, schema type, and similar.

documentTypeListItems():ListItem[]

Convenience method. Returns an array of list items for all defined document types in your schema, and configure them with the correct titles, icons, initial value templates and similar.

export const structure = (S) =>
  S.list()
    .title('Content')
    .items(
      // List all document types except "siteSettings"
      S.documentTypeListItems().filter(
        item => item.getId() !== 'siteSettings'
      )  
    )

divider():

Inserts a visual divider in a list.

//sanity.config.js

import {structure} from './structure'

export default defineConfig({
  ...
  plugins: [
    structureTool({
      structure
    }),
  ],
  schema: schemaTypes
})

// ./structure.js (.ts)

export const structure = (S) =>
  S.list()
    .title('Content')
    .items([
      // Make a singleton of the document with ID “siteSettings”
      S.documentListItem()
        .id('siteSettings')
        .schemaType('siteSettings'),
      // Add a visual divider
      S.divider(),
      // Add the rest of the document types, but filter out the siteSettings type defined above
      ...S.documentTypeListItems().filter(
        item => item.getId() !== 'siteSettings'
      )
    ])

The document node type represents (as the title implies) a document. Often, it is referred to as "the editor node" since it's common for it to render a form allowing you to edit the document in question. However, it can also render other "views" of the document, which is why it has a more generic name.

The following methods let you configure what happens when you open a document. If no views are specified for a document node, it will return the default form view.

document():Document

A primitive for defining a document node.

documentWithInitialValueTemplate(templateId, parameters):Document

Convenience method for building a document node with a specific initial value template and set of parameters. Automatically configures the document with the correct schema type.

Returns a document node and as such, has the same builder methods as document().

Many of the nodes in the structure builder (such as the document type list) automatically render a document node as a child if none is provided. While you can take full control of every node in the structure, this is sometimes a bit tedious if you usually return the same document node for every document or schema type.

The structure definition allows for defining a function which is called when the "default" should be resolved.

While the structure definition you provide is exported as the default export, you can also export a function named getDefaultDocumentNode that will be called in these situations:

getDefaultDocumentNode(options):Document

Export a function named getDefaultDocumentNode that returns an S.document() node to set the default configuration for document nodes (also often referred to as an "editor node" since it often contains the form view used to edit a document).

// sanity.config.ts (.js)

import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {structure, defaultDocumentNode} from './structure'
import { schemaTypes } from './schema'

export default defineConfig({
  name: 'default',
  title: 'My Cool Project',
  projectId: 'my-project-id',
  dataset: 'production',
  plugins: [
    structureTool({
      structure,
      defaultDocumentNode,
    }),
  ],
  schema: schemaTypes
})

// ./structure.js (.ts)
import { WebPreview, JsonView } from './previews'

export const structure = (S, context) =>
  S.list()
    .title('Content')
    .items([
      S.listItem()
        .title('Settings')
        .child(
          S.document()
            .schemaType('siteSettings')
            .documentId('siteSettings')
        ),
      ...S.documentTypeListItems()
    ])

export const getDefaultDocumentNode = (S, {schemaType}) => {
 // Conditionally return a different configuration based on the schema type
 if (schemaType === "post") {
   return S.document().views([
     S.view.form(),
     S.view.component(WebPreview).title('Web')
   ])  
 }
 return S.document().views([
   S.view.form(),
   S.view.component(JsonView).title('JSON')
 ])
}

export default S.defaults()

Within a document pane, there can be one or more views. If there are more than one view node, they will appear as tabs. The views can be built using methods exposed on S.view - eg S.view.form()

form():FormView

The form method returns the default form-based editor for the specified document type.

S.view.form()

component(reactComponent):ComponentView

The component method takes a React component and renders it into the document view. It's most often used for showing the values of a document in alternative ways to the default document form.

export const structure = (S) =>
  S.documentTypeList('sampleProject')
    .child(id =>
      S.document()
        .schemaType('sampleProject')
        .documentId(id)
        .views([
          // The default form for editing a document
          S.view.form(),
          
          // Render the current selected document’s values as JSON
          S.view.component(({document}) => (
            <pre>{JSON.stringify(document.displayed, null, 2)}</pre>
          )).title('View JSON')
        ])
    )

Each pane may have a menu in its upper right corner. This is where you usually find ordering options and affordances for adding new documents. Menus can also hold initial value templates. The convenience list methods will automatically set up default menus for you (some of these may also require that you add schemaType()).

menuItem():MenuItem

orderingMenuItem({title, by}):MenuItem

Convenience method for populating the menu for selecting different fields and directions for ordering a list of documents.

 S.documentList()
  .title("Products")
  .filter("_type == $type")
  .params({ type: "product" })
  .menuItems([
    ...S.documentTypeList("product").getMenuItems(),
    S.orderingMenuItem({title: 'Title ascending', by: [{field: 'title', direction: 'asc'}]}),
    S.orderingMenuItem({title: 'Title descending', by: [{field: 'title', direction: 'desc'}]})
  ])

orderingMenuItemsForType(typeName):MenuItem[]

Convenience method for returning an array of menu items used to order documents of a given schema type, based on the orderings defined in the schema definition.

menuItemsFromInitialValueTemplateItems(items):MenuItem[]

Convenience method for returning an array of menu items used to create new documents based on the given initial value template items.

Note: You should consider using the initialValueTemplates() method on the pane instead of this method unless you want the menu items to be nested inside the actual menu.

 S.documentList()
  .title('Craft beer & cider')
  .filter('_type in $types && isCraft == true')
  .params({types: ['beer', 'cider']})
  .menuItems(
    S.menuItemsFromInitialValueTemplateItems([
      S.initialValueTemplateItem('beer', {isCraft: true}),
      S.initialValueTemplateItem('cider', {isCraft: true}),
    ])
  )