Skip to main content
The Structure Tool is the default content editing interface in Sanity Studio. Use the Structure Builder API to customize how your content is organized and displayed.

​
structureTool

Define and configure a Structure Tool instance. 
import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'

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

​
Options

​
name
string
Tool identifier. Default: 'structure'
​
title
string
Tool display title. Default: 'Structure'
​
icon
ComponentType
Tool icon component. Default: MasterDetailIcon
​
structure
StructureResolver
Function that returns the structure configuration
​
defaultDocumentNode
DefaultDocumentNodeResolver
Function that returns the default document pane configuration

​
Structure Builder

The Structure Builder API provides a fluent interface for configuring your Studio’s structure.

​
Basic Example

import {structureTool} from 'sanity/structure'

export default defineConfig({
  plugins: [
    structureTool({
      structure: (S) =>
        S.list()
          .title('Content')
          .items([
            S.documentTypeListItem('article').title('Articles'),
            S.documentTypeListItem('author').title('Authors'),
            S.divider(),
            S.listItem()
              .title('Settings')
              .child(
                S.document()
                  .schemaType('siteSettings')
                  .documentId('siteSettings')
              ),
          ]),
    }),
  ],
})

​
Structure Builder API

The Structure Builder (typically aliased as S) provides methods for building your structure.

​
S.list()

Create a list of items. 
S.list()
  .title('Content')
  .items([
    // List items
  ])
​
title
string
List title
​
items
ListItem[]
Array of list items
​
id
string
Unique list identifier

​
S.documentTypeListItem()

Create a list item for a document type. 
S.documentTypeListItem('article')
  .title('Articles')
  .icon(DocumentIcon)
​
schemaType
string
required
Document type name
​
title
string
Override the display title
​
icon
ComponentType
Custom icon component
​
child
DocumentListBuilder
Custom child configuration

​
S.documentTypeList()

Create a list of documents of a specific type. 
S.documentTypeList('article')
  .title('Articles')
  .filter('_type == $type && published == true')
  .params({type: 'article'})
​
schemaType
string
required
Document type name
​
filter
string
GROQ filter for the list
​
params
Record<string, any>
Parameters for the filter
​
defaultOrdering
SortOrdering[]
Default sort order

​
S.listItem()

Create a custom list item. 
S.listItem()
  .title('Custom Item')
  .icon(GearIcon)
  .child(
    S.document()
      .schemaType('settings')
      .documentId('siteSettings')
  )
​
title
string
required
Item title
​
id
string
Item identifier
​
icon
ComponentType
Item icon
​
child
StructureNode
Child structure node

​
S.document()

Create a document pane. 
S.document()
  .schemaType('article')
  .documentId('article-123')
  .views([
    S.view.form(),
    S.view.component(Preview).title('Preview'),
  ])
​
schemaType
string
required
Document type
​
documentId
string
required
Document ID
​
title
string
Document pane title
​
views
View[]
Document views

​
S.divider()

Create a visual divider. 
S.list()
  .items([
    S.documentTypeListItem('article'),
    S.divider(),
    S.documentTypeListItem('author'),
  ])

​
Document Views

Customize how documents are displayed.

​
S.view.form()

The default form view. 
S.view.form()

​
S.view.component()

Custom component view. 
import {Preview} from './components/Preview'

S.view.component(Preview)
  .title('Preview')
  .icon(EyeIcon)
​
component
ComponentType
required
React component to render
​
title
string
View title
​
icon
ComponentType
View icon

​
defaultDocumentNode

Configure default views for documents. 
import {structureTool} from 'sanity/structure'
import {IframePreview} from './components/IframePreview'

export default defineConfig({
  plugins: [
    structureTool({
      defaultDocumentNode: (S, {schemaType}) => {
        // Add preview for specific types
        if (schemaType === 'article') {
          return S.document().views([
            S.view.form(),
            S.view.component(IframePreview).title('Preview'),
          ])
        }
        
        // Default for all other types
        return S.document().views([S.view.form()])
      },
    }),
  ],
})
​
S
StructureBuilder
required
Structure Builder instance
​
context
object
required
Context object
​
schemaType
string
Document type name
​
documentId
string
Document ID

​
Advanced Example

import {structureTool} from 'sanity/structure'
import {DocumentIcon, CogIcon, UsersIcon} from '@sanity/icons'

export default defineConfig({
  plugins: [
    structureTool({
      structure: (S) =>
        S.list()
          .title('Content')
          .items([
            // Articles section
            S.listItem()
              .title('Articles')
              .icon(DocumentIcon)
              .child(
                S.list()
                  .title('Articles')
                  .items([
                    S.listItem()
                      .title('Published')
                      .child(
                        S.documentList()
                          .title('Published Articles')
                          .filter('_type == "article" && published == true')
                      ),
                    S.listItem()
                      .title('Drafts')
                      .child(
                        S.documentList()
                          .title('Draft Articles')
                          .filter('_type == "article" && published != true')
                      ),
                    S.divider(),
                    S.listItem()
                      .title('All Articles')
                      .child(S.documentTypeList('article')),
                  ])
              ),

            // Authors
            S.documentTypeListItem('author')
              .title('Authors')
              .icon(UsersIcon),

            S.divider(),

            // Singleton settings
            S.listItem()
              .title('Settings')
              .icon(CogIcon)
              .child(
                S.document()
                  .schemaType('siteSettings')
                  .documentId('siteSettings')
                  .title('Site Settings')
              ),
          ]),

      defaultDocumentNode: (S, {schemaType}) => {
        if (schemaType === 'article') {
          return S.document().views([
            S.view.form(),
            S.view.component(PreviewPane).title('Preview'),
          ])
        }
        return S.document().views([S.view.form()])
      },
    }),
  ],
})

Build docs developers (and LLMs) love

Get started for freeTalk to us