List Items

The core of Sanity Structure Tool is the ListItem configuration. This guide explains every property you can use to define your desk structure.

title

• Type: string
• Optional: Yes (Required if children is present)
• Examples: See Examples

The display name for the list item. While optional for standard items (where it can be inferred from schemaType), it is mandatory for items that act as folders (containing children).

{
  title: 'My Custom Title',
}

schemaType

• Type: string
• Optional: Yes
• Examples: See Examples

The name of the document type defined in your Sanity schema. Providing this will automatically link the list item to that document type.

{
  schemaType: 'author',
}

icon

• Type: IconComponent | ComponentType | ReactNode
• Optional: Yes
• Examples: See Examples

The icon to display to the left of the title. You can use standard Sanity icons or custom React components.

import { UserIcon } from '@sanity/icons';

{
  schemaType: 'author',
  icon: UserIcon,
}

singleton

• Type: boolean
• Optional: Yes (Default: false)
• Examples: See Examples

When set to true, this item is treated as a single document rather than a list. The plugin will automatically handle the document ID and editor view.

{
  title: 'Global Settings',
  schemaType: 'settings',
  singleton: true,
}

children

• Type: ListItem[]
• Optional: Yes
• Examples: See Examples

An array of ListItem objects to create a nested list. This is the primary way to build hierarchical structures.

Note

When adding children, you must also provide a title so it can be labeled correctly in the desk menu.

{
  title: 'Profile',
  children: [
    {
      schemaType: 'author',
    },
    {
      schemaType: 'user',
    },
  ],
}

isDivider

• Type: boolean
• Optional: Yes (Default: false)
• Examples: See Examples

When set to true, this item renders as a visual separator in the desk list. Other properties (except title) are ignored.

{
  title: 'Content Section',
  isDivider: true,
}

filter

• Type: string | ((params: { currentUser: CurrentUser }) => string)
• Optional: Yes
• Examples: See Examples

A GROQ filter string to limit which documents are shown in the list. You can also pass a function that returns a filter string based on the current user.

{
  schemaType: 'author',
  filter: 'isActive == true',
}

filterParams

• Type: Record<string, unknown> | ((params: { currentUser: CurrentUser }) => Record<string, unknown>)
• Optional: Yes
• Examples: See Examples

Parameters to be used within the filter GROQ string.

{
  schemaType: 'author',
  filter: 'type == $type',
  filterParams: {
    type: 'news'
  },
}

hideAddButton

• Type: boolean
• Optional: Yes (Default: false)
• Examples: See Examples

When set to true, the "Add" button (plus icon) will be hidden for this document list.

{
  schemaType: 'author',
  hideAddButton: true,
}

isPlural

• Type: boolean
• Optional: Yes (Default: true)
• Examples: See Examples

Controls whether the auto-generated title should be pluralized when no custom title is provided.

Note

For items marked as singleton: true, pluralization is disabled by default since singletons are singular by nature. However, you can manually set isPlural: true if you wish to pluralize a singleton's title.

Recommendation

We recommend giving your schema a singular title (e.g., Author instead of Authors). The plugin will then automatically pluralize it for the list view (e.g., "Authors").

When isPlural is set to false, the plugin will showcase the exact same name you have defined in your schema, without any pluralization logic applied.

{
  schemaType: 'author',
  isPlural: false,
}

workspaces

• Type: string[] | ((params: { defaultWorkspaces: string[] }) => string[])
• Optional: Yes
• Examples: See Examples

Restricts the visibility of the list item to specific Sanity workspaces. You can provide either a static array of workspaces or a function that returns an array based on the defaultWorkspaces defined in your plugin configuration.

Note

When using a static array, the provided values are concatenated with the defaultWorkspaces. When using a callback function, the returned array is treated as the final value, giving you full control over the resulting list.

{
  schemaType: 'adminSettings',
  workspaces: ['workspace1'],
}

roles

• Type: string[] | ((params: { defaultRoles: string[] }) => string[])
• Optional: Yes
• Examples: See Examples

Restricts the visibility of the list item to specific user roles. Like workspaces, this can be a static array or a function receiving the defaultRoles.

Note

When using a static array, the provided values are concatenated with the defaultRoles. When using a callback function, the returned array is treated as the final value, giving you full control over the resulting list.

{
  schemaType: 'settings',
  roles: ['administrator', 'editor'],
}

templates

• Type: Record<string, unknown>
• Optional: Yes
• Examples: See Examples

Used to pass initial value templates for new documents created from this list item.

{
  schemaType: 'post',
  templates: {
    isActive: false,
  },
}

raw

• Type: (S: StructureBuilder, context: StructureResolverContext) => ListItem
• Optional: Yes
• Examples: See Examples

The "Escape Hatch". Allows you to use the native Sanity Structure Builder API directly for this specific item. You also have access to the context (containing currentUser, projectId, etc.).

{
  raw: (S) => S.listItem().title('Advanced Item').child(...),
}

Use Sparingly

When using raw, you are responsible for handling your own visibility logic (workspaces/roles) for any nested children.