Helpers

The Sanity Structure Tool provides a set of helper functions that are strictly typed to your project's specific configuration.

These helpers are generated by a factory function (structureToolPlugin), ensuring that your custom roles and workspaces are fully available via IntelliSense and validated at compile-time.

The Factory Pattern

When you initialize the plugin, you receive a helpers object that is pre-bound to your types, which you then use to define your structure list items:

src/structure/index.ts

import { structureToolPlugin } from 'sanity-plugin-structure-tool';

export const { helpers } = structureToolPlugin({
  // 1. Define your project-specific roles and workspaces
  roles: ['administrator', 'editor', 'viewer'],
  workspaces: ['production', 'staging'],
});

src/structure/listItems.ts

helpers.listing('post', {
  // Roles and Workspaces are now strictly typed!
  roles: ['administrator'],
  workspaces: ['production'],
});

helpers.children

• Shorthand Signature: (title: string, children: ListItem[], params?: CoreParams) => ChildrenOutput
• Object Signature: (params: ChildrenParams) => ChildrenOutput
• Examples: See Examples

Creates a nested list structure (folder).

JSON

{
  title: 'Settings',
  children: [
    {
      schemaType: 'generalSettings',
      singleton: true,
    },
    {
      schemaType: 'apiSettings',
      singleton: true,
    },
  ],
}

Helpers (Short)

helpers.children('Settings', [
  helpers.singleton('generalSettings'),
  helpers.singleton('apiSettings'),
]);

Helpers (Object)

helpers.children({
  title: 'Settings',
  children: [helpers.singleton('generalSettings'), helpers.singleton('apiSettings')],
});

helpers.component

• Shorthand Signature: (title: string, component: ComponentType, params?: CoreParams) => ComponentOutput
• Object Signature: (params: ComponentParams) => ComponentOutput
• Examples: See Examples

Renders a custom React component as the pane content.

JSON

{
  title: 'Dashboard',
  component: MyDashboard,
}

Helpers (Short)

helpers.component('Dashboard', MyDashboard);

Helpers (Object)

helpers.component({
  title: 'Dashboard',
  component: MyDashboard,
});

helpers.divider

• Shorthand Signature: (title?: string, params?: CoreParams) => DividerOutput
• Object Signature: (params?: DividerParams) => DividerOutput
• Examples: See Examples

Renders a visual separator in the desk list.

JSON

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

Helpers (Short)

helpers.divider('Content Section');

Helpers (Object)

helpers.divider({
  title: 'Content Section',
});

helpers.filters

• Type: (params: FiltersParams) => FiltersOutput
• Examples: See Examples

Creates a filtered list (e.g., "Drafts", "Published").

JSON

{
  title: 'Published Posts',
  filter: '_type == "post" && !(_id in path("drafts.**"))',
}

Helpers

helpers.filters({
  title: 'Published Posts',
  filter: '_type == "post" && !(_id in path("drafts.**"))',
});

helpers.listing

• Shorthand Signature: (schemaType: string, params?: CoreParams) => ListingOutput
• Object Signature: (params: ListingParams) => ListingOutput
• Examples: See Examples

Used to define a standard document list.

JSON

{
  title: 'All Authors',
  schemaType: 'author',
  icon: UserIcon,
}

Helpers (Short)

helpers.listing('author', {
  title: 'All Authors',
});

Helpers (Object)

helpers.listing({
  title: 'All Authors',
  schemaType: 'author',
  icon: UserIcon,
});

helpers.raw

• Shorthand Signature: (raw: (S: StructureBuilder, context: any) => any, params?: CoreParams) => RawOutput
• Object Signature: (params: RawParams) => RawOutput
• Examples: See Examples

The "Escape Hatch" to use the native Sanity Structure Builder API.

JSON

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

Helpers (Short)

helpers.raw((S) => S.listItem().title('Advanced').child(...))

Helpers (Object)

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

helpers.singleton

• Shorthand Signature: (schemaType: string, params?: CoreParams) => SingletonOutput
• Object Signature: (params: SingletonParams) => SingletonOutput
• Examples: See Examples

Used for singleton documents (documents that only have one instance).

JSON

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

Helpers (Short)

helpers.singleton('settings', {
  title: 'Global Settings',
});

Helpers (Object)

helpers.singleton({
  title: 'Global Settings',
  schemaType: 'settings',
});

Why a Factory Pattern?

By using a factory function (structureToolPlugin) to generate your helpers, we ensure that:

1. Context is preserved: Helpers are pre-bound and know the specific "shape" of your structure.
2. No generic "string" types: Roles and Workspaces are treated as literal unions, not just broad strings.
3. Refactoring is easy: If you change a role name in your configuration, TypeScript will immediately highlight all the helpers that need to be updated.

Usage via Callbacks (No Imports)

If you do not want to import the generated helpers object in every structure file, both defineListItems and defineListItem support a callback function that passes the bound helpers as an argument. This is especially useful for modular structures:

src/structure/listItems.ts

import { defineListItems } from './index';

export default defineListItems(({ helpers }) => [
  helpers.divider('General'),
  helpers.listing('author'),
  helpers.singleton('settings'),
]);

Advantages of Helpers

Using the built-in helpers offers several key advantages:

1. Readability: The syntax is often more expressive and closer to natural language.
2. Type Safety: Every helper is strictly typed to ensure you provide the correct parameters for each item type.
3. Type Intelligence: If you configured roles or workspaces in your setup, they will be available as autocomplete options within the helper parameters.
4. Shorthand Syntax: Many helpers allow you to pass the schemaType or title as the first argument, reducing boilerplate.