New release: Conditional Fields

Set up Structure Builder to override the default list view

In this article, we'll explore how to initialize Structure Builder and override the default title of the "Content" list.

In this article, we'll use the Structure Builder API to modify the default list view for a Sanity Studio. If you're unfamiliar with the concepts behind Structure Builder, be sure to read the introductory article.

Learning the Structure Builder API

This collection of articles will walk you through all the basics of using Structure Builder to create custom editing experiences.

Setting up Structure Builder for your project

The studio comes with a default structure when it's installed. In order to override the default behavior, the studio needs to be told where to look for the structure. This is done by leveraging the parts system. In this case, an entry needs to be added to the parts array in sanity.json (see highlighted code), located at the root level of your studio folder. That will let the studio know where your configuration file is.

Once the configuration is modified, the deskStructure.js file should be added to the root of the studio.

// /sanity.json
{
  "root": true,
  "project": {
    "name": "porfolio"
  },
  "api": {
    "projectId": "projectId",
    "dataset": "dataset"
  },
  "plugins": [
    "@sanity/base",
    "@sanity/components",
    "@sanity/default-layout",
    "@sanity/default-login",
    "@sanity/dashboard",
    "@sanity/desk-tool"
  ],
  "parts": [
    {
      "name": "part:@sanity/base/schema",
      "path": "./schemas/schema.js"
    },
{
"name": "part:@sanity/desk-tool/structure",
"path": "./deskStructure.js"
}
] }

Protip

The code can live anywhere in your project. For simple structures, having it in the root in one file makes sense. For larger customizations with multiple components, it's considered a best practice to move this code into its own folder.

If you restart the local development server (ctrl + C and then sanity start), you will get an error message. Don't worry, this is expected. This is because the default structure from the studio core has been replaced with a blank file. From this blank slate, a new structure needs to be defined.

Defining a new default structure

To define a new structure, the code should be added to the deskStructure.js file. In order to use the Structure Builder API, it must be imported into the file, and a function using it should be the default export.

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

export default () =>
  S.list()
    .title('Base')
    .items(
      S.documentTypeListItems()
    )

Let's break these methods down.

S.list()

The .list() method generates a new generic list. Since it's not a child node, it will appear in the first pane of the studio. In most use cases, the documentTypeList or documentList will be preferred, since they have additional convenience methods. For the first pane of studio, the generic list works the best.

.title()

The .title() method exists nested on methods that create various types of panes and accepts a string as its argument. In this case, we'll change the title of our initial panel to be "Base" instead the default "Content."

Protip

Each panel should have an ID defined. If a title is provided, but no ID, the ID will be generated from the title of the pane.

This ID will be used to generate routes in the studio.

If we stop here, the studio will now load. It will contain an initial panel with no content. We need to tell our generic list what items should be listed.

.items()

The .items() method is used to define the contents of a list panel. The method will take an array of items to populate the list. Typically, it will accept a complementary method from Structure Builder, such as listItem or documentListItem. In this case, the initial panel of the studio should populate with a list of document types.

S.documentTypeListItems()

The documentTypeListItems() method will find all the document types created by the schema defined in schema.js and display links to lists of documents that are of that type.

Next steps

From here, there's a working instance of Structure Builder in the project. In the next tutorial, we'll look at adding a link to edit a specific document in the first panel we just rebuilt.

Was this article helpful?