Studio plugin configuration reference

Options, mapping rows, structure helpers, and embeddable tables of @sanity/workflow-studio-plugin, and how it differs from the @sanity/workflow-studio adapter.

This page lists the configuration options of @sanity/workflow-studio-plugin: the workflowStudioPlugin options, mapping rows, the structure helpers, and the table components you can embed in a custom Studio tool. To install the plugin and start a workflow from the document editor, follow Add Workflows to Sanity Studio.

The plugin has these peer dependencies:

• sanity 6.15 or later in the 6.x line
• react and react-dom 19.2.7 or later
• styled-components 6.4.2 or later
• @sanity/sdk 3.1 or later in the 3.x line
• @sanity/workflow-components, @sanity/workflow-diagram, @sanity/workflow-engine, @sanity/workflow-react, and @sanity/workflow-studio, all at the same version as the plugin

import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {
  workflowDefaultDocumentNode,
  workflowStudioPlugin,
} from '@sanity/workflow-studio-plugin'

export default defineConfig({
  // ...your projectId, dataset, schema...
  plugins: [
    structureTool({defaultDocumentNode: workflowDefaultDocumentNode()}),
    workflowStudioPlugin({
      partition: 'dev',
      mappings: [
        {
          docType: 'article',
          definition: 'article-review',
          label: 'Article review',
          autoStart: true,
        },
      ],
    }),
  ],
})

workflowStudioPlugin(config) is a Studio plugin factory. Add its return value to plugins in defineConfig. The plugin validates config when sanity.config.ts is evaluated, so a configuration error stops the Studio from starting.

WorkflowPluginConfig is the options object passed to workflowStudioPlugin. Every property is optional and read-only.

A mapping row binds one Studio document type to one deployed definition. If the plugin already found that docType and definition pair on its own, the row replaces what it found. Otherwise, the row adds the pair. One document type can appear on several rows. Two rows for the same pair throw an error when sanity.config.ts is evaluated, and the Studio doesn’t start.

Without mapping rows, the plugin finds bindings on its own. It reads the latest deployed version of each definition. It binds every startable workflow whose subject field takes its value from user input and accepts a document type in your Studio schema.

Add a row when you need to do any of these:

• Bind a reserved sanity. or system. document type.
• Bind a definition that uses a doc.ref field named subject instead of a subject field.
• Turn on autoStart.
• Change the label, start values, or perspective.

If a row’s definition isn’t deployed, or its start values don’t fit the deployed definition, the plugin disables the row instead of throwing. The row’s start control then shows Unavailable — this workflow isn’t set up correctly for <Type> documents. The reason appears in two places: under Setup issue on that workflow’s page in the Workflows tool, and in the browser console, prefixed with [workflow-studio-plugin].

The plugin disables a row when it seeds any of these:

• A field that’s undeclared, duplicated, of the wrong kind, or not filled from input
• A document type that the subject’s types doesn’t accept
• A local document type that the Studio schema doesn’t declare
• One of the engine’s own document types

A required input that the row leaves unset isn’t an error. The start dialog asks the editor for it.

import {structureTool} from 'sanity/structure'
import {workflowsView} from '@sanity/workflow-studio-plugin'

structureTool({
  defaultDocumentNode: (S, {schemaType}) =>
    schemaType === 'article'
      ? S.document().views([S.view.form(), workflowsView(S)])
      : S.document(),
})

RunsTable shows workflow runs, and ForMeTable shows tasks assigned to one person. Both tables look and behave like the ones in the Workflows tool, with document previews, member avatars, task hints, and virtualized rows. Render them inside a Studio that uses workflowStudioPlugin. Put them in a container with a fixed height and overflowY: 'auto', so the rows can scroll. The tables need Studio providers, so they don’t work outside Studio. For controls outside Studio, use Reusable UI components.

The tables are controlled components. Your tool does the rest:

• Load the data, and render the loading, error, and empty states.
• Filter and sort rows before you pass them in.
• Manage selection, focus, and keyboard navigation.
• Reset the scroll position when the scope or sort changes.

A row shows its task as late only when the row’s overdueSince is set. The late span counts from that date. forMeTaskRowsOf sets overdueSince while the task is open on a running workflow and one of its due dates has passed. It measures against the now you passed to runRowsOf. So derive rows again with the same clock you pass to the table as now. If you build a ForMeTaskRow yourself, set its overdueSince.

• runRowsOf({previews, definitions, now})(): RunRow[]

  Builds one row per instance preview. A run preview is a reduced instance record used in lists. definitions is a ReadonlyMap of deployed definitions by name, used for titles; a missing definition falls back to its raw name. Include settled parent previews so a spawned child keeps its root document attribution. now is the moment overdue is measured against.

• forMeTaskRowsOf({rows, who})(): ForMeTaskRow[]

  Selects the tasks in rows that who holds, one row per task. who is {userId, roles}: an account-global user ID and resolved project role names. A direct assignment outranks a held role.

The package also exports the row and sort types these props use: RunRow, RunAttention, RunAttentionDetail, RunBlockedDetail, RunOverdueDetail, ForMeTaskRow, StageTask, AssignmentIdentity, TaskAssignment, TaskHolding, RunsScope, RunSort, RunSortKey, ForMeSort, ForMeSortKey, and RunNavigationKeyEvent. See TypeDoc for their fields.