Desk Tool API

How to use the Desk Tool API to configure your desk tool(s).

A “desk tool” is a top-level view within Sanity Studio in which content editors can drill down to specific documents to edit them. With the Desk Tool API, you can configure your Studio's desk tool(s).

Properties

  • name

    The name you want this desk to have (among other places, this name is used in routing, if name is set to “desk”, it is shown on /desk). Usually lowercase or camelcase by convention. Defaults to desk.

  • title

    The title that will be displayed for the tool. Defaults to Desk

  • icon

    React icon component for the tool, used in navigation bar. Defaults to MasterDetailIcon from @sanity/icons

  • structure

    A structure resolver function. Receives two arguments:

    • S - an instance of the structure builder, that can be used to build the lists/items/panes for the desk tool
    • context - an object holding various context that may be used to customize the structure, for instance the current user.

    Defaults to (S) => S.defaults()

  • defaultDocumentNode

    A resolver function used to return the default document node used when editing documents. Receives two arguments:

    • S - an instance of the structure builder, that can be used to build the document node (S.document())
    • context - an object holding various context that may be used to customize the document node

Minimal Example

The sanity/desk package exports a deskTool, which is a plugin that installs a desk tool. You can add it to your studio by passing it as part of the plugins array.

// sanity.config.ts
import { defineConfig } from 'sanity'
import { deskTool } from 'sanity/desk'

export default defineConfig((
	// ...
  plugins: [
    deskTool() // use defaults
  ]
})

To customise your desk tool, pass an object in with the settings you want to customise. For instance, if you want a custom desk tool called “cars” that shows in the toolbar as “Cars”, and has an icon from react-icons and tweaks both the structure and defaultDocumentNode:

// sanity.config.ts
import { defineConfig } from 'sanity'
import { deskTool } from 'sanity/desk'
import { FaCar } from 'react-icons'

export default defineConfig((
	// ...
  plugins: [
    deskTool({
      name: 'cars',
      title: 'Cars',
      icon: FaCar,
      structure: (S) => S.documentTypeList('car'),
      defaultDocumentNode: (S) =>
        S.document().views([
          S.view.form(),
          S.view.component(Preview).title('Preview')
        ])
    })
  ]
})

Was this article helpful?