Structure Builder Reference

An overview of the main methods in Structure Builder

This is comprehensive list of methods and parameters for the Structure Builder. We also have a general introduction to using Structure Builder.

The methods in the Structure Builder can be grouped into the individual methods that controls different parts of the desk tool, and convenience methods that does much of the heavy lifting for you (sets titles, actions, menu items and so on). The convenience methods typically takes a simple parameter (e.g. a type name). The structure builder is written in TypeScript, which gives support for autocomplete and various features in editors that supports it (e.g. IntelliSense in VS Code).

documentTypeList

Convenience method for returning a list of documents by type.

Parameters

Methods

Example

import S from '@sanity/desk-tool/structure-builder';

const preview = () =>
  S.list()
    .title("Content")
    .items([
      S.listItem()
      .title('Cheap products')
      .child(
        S.documentTypeList('product')
          .filter('defaultProductVariant.price < 5')
          .defaultOrdering([{field: 'defaultProductVariant.price', direction: 'desc'}])
      ),
Filter products by a parameter

documentTypeListItem

Convenience method for returning an item for a document type list.

Parameters

Methods

Example

import S from "@sanity/desk-tool/structure-builder";

export default () =>
  S.list()
    .title('Content')
    .items([
      S.documentTypeListItem('product')
    ])

documentTypeListItems

Convenience method for listing all document types from schemas with their respective actions, menus, documents, and editors.

Example:

import S from "@sanity/desk-tool/structure-builder";

export default () =>
  S.list()
    .title('Content')
    .items([
      ...S.documentTypeListItems()
    ])

list

A list with a defined set of list items.

Methods

Example

import S from "@sanity/desk-tool/structure-builder";

const preview = () =>
  S.list()
    .title('Content')
    .items(/* Menu items goes here */)

listItem

A list item

Methods

import S from "@sanity/desk-tool/structure-builder";
import Link from "react-icons/lib/md/link"

export default () =>
  S.list()
    .title('Content')
    .items([
      S.listItem()
        .title('A list item!')
        .icon(Link)
    ])

divider

A simple divider, renders an <hr/> in the list.

Example

import S from '@sanity/desk-tool/structure-builder'

export default
  S.list()
    .id('content')
    .title('Content')
    .items([
      S.listItem().title('A list item'),
      S.divider(),
      S.listItem().title('Another list item'),
    ])

documentList

Returns a list of documents based on a GROQ filter expression

Methods

Example:

import S from "@sanity/desk-tool/structure-builder";

export default () =>
  S.documentList()
    .title('Products')
    .filter('_type == $type')
    .params({ type: 'product'})

documentListItem

Convenience method for a list item with a specific child of a type

Methods

import S from '@sanity/desk-tool/structure-builder'

const preview = () =>
S.list()
  .title('Content')
  .items([
    S.documentListItem()
      .id('global-config')
      .title('Configuration')
      .schemaType('config')
  ])

editor

Places an editor in the current pane.

Parameters

Methods

Example

import S from '@sanity/desk-tool/structure-builder'

export default () =>
  S.list()
    .title('Content')
    .items([
      S.listItem()
        .title('Global configuration')
        .child(
          S.editor()
            .id('global-config')
            .schemaType('config')
            .documentId('global-config')
        )
    ])

component

Renders a custom React component in the pane.

Example

import React from 'react' // if you want to write JSX
import S from "@sanity/desk-tool/structure-builder";

export default () =>
  S.list()
    .title('Content')
    .items([
      S.listItem()
      .title('Custom component')
      .child(
        S.component()
        .title('My custom component')
        .component(props => <pre>{JSON.stringify(props, null, 2)}</pre>)
      )
    ])

menuItem()

A menu item

Methods

menuItemGroup()

Group items in a menu

orderingMenuItem(params)

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

Example of an ordering menu

Parameters

  • titlestring

    Title of the ordering to show in the menu

  • byarray

    An array of objects consisting of the field to sort by and the direction of the ordering (asc or desc). See example below.

Example

 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

Orderings from the schema

initialValueTemplateItem(templateId, params?)

Creates a reference to an initial value template, with an optional set of parameters. Can be used to declare which initial value templates are valid for a list, as well as for the "new document" menu.

Takes the ID of the referenced initial value template as the first argument and an optional object of parameters for the template as the second.

Returns an instance of an initial value template item builder, which can be further customized by calling methods on the builder.

Methods

  • REQUIREDtemplateIdstring

    The ID of the referenced template

  • parametersobject

    Object of parameters to use for the initial value template

  • idstring

    ID of the template menu item. Will use the id of the template if not provided. If multiple items within the array reference the same template, use this to specify a unique identifier.

  • titlestring

    Title for the menu item. If none is specified, the title for the template is used.

  • descriptionstring

    Used to override the description of the template, for instance when giving a specific set of parameters

defaultInitialValueTemplateItems

Returns an array of items for all declared initial value templates which can be created and do not require parameters.