The reactive session

Use a reactive session to keep a custom Editorial Workflows interface synchronized, preview field edits, and commit actions safely.

A reactive session is the live, UI-facing view of one workflow instance. Use it when you are building a custom Editorial Workflows surface that must stay current as the instance, referenced content, or guards change.

An evaluation is the engine’s current read-only view of stages, activities, fields, and action verdicts. The session refreshes that evaluation as observed content changes. Writes happen only when your interface calls tick, fireAction, or editField.

In an App SDK application, useWorkflowSession supplies the current evaluation and the commands that can change the instance. Handle unreadable data and live-read failures before rendering workflow controls.

import {useWorkflowSession} from '@sanity/workflow-sdk'
import type {Engine} from '@sanity/workflow-engine'

interface WorkflowPanelProps {
  engine: Engine
  instanceId: string
}

export function WorkflowPanel({engine, instanceId}: WorkflowPanelProps) {
  const session = useWorkflowSession({engine, instanceId})

  if (session.invalid) return <p>This workflow data cannot be read.</p>
  if (session.error) return <p>The workflow could not be loaded.</p>
  if (!session.ready || !session.evaluation) return <p>Loading workflow…</p>

  return <pre>{JSON.stringify(session.evaluation, null, 2)}</pre>
}

The example renders the raw evaluation so the data flow is visible. A real interface uses the same value to render stages, activities, fields, and controls. Call the session commands in response to deliberate user actions.

The adapter observes the instance, the documents its conditions read, and its active guards. The session waits for those sources before setting ready and producing its first evaluation. Later emissions recompute that evaluation automatically.

A command still commits through the engine. After tick, fireAction, or editField settles, the session evaluates the committed result immediately instead of waiting for the observer to echo the write.

In a custom App SDK UI, the adapter observes synchronized documents from the Content Lake and feeds them into the reactive session. The editor can preview a tentative field value before the session invokes an engine commit and returns the settled evaluation.

• invalid means an engine-owned document cannot be read safely. A model-ahead result requires a newer engine. A shape violation requires investigation. Show remediation instead of a spinner.
• error means an observer read failed. The state clears when the stream recovers.
• !ready or a missing evaluation means the session is still synchronizing. This also prevents the previous evaluation from appearing while switching instance IDs.
• ready with an evaluation means the interface can render stages, activities, fields, and action verdicts.

Use previewField while a person is typing. It changes the projected field value and any advisory verdicts derived from that value, but it never changes the committed stage, activity status, or history.

Call editField at a deliberate boundary such as blur, Enter, Save, or a single picker gesture. Every call is a real engine commit with history, guard refresh, and transition evaluation. Never call it for each keystroke.

Call discardFieldPreview when editing ends without a commit. The next evaluation returns to the committed value.

Do not infer whether an action should appear. Use the evaluated action model described in Activities and actions.

• A failed filter removes the action from the interface.
• An action with when is a cascade trigger, not a button. Describe its future behavior from whenInsight. See Evaluation insights for the complete explanation contract.
• For a visible manual action, use its verdict to decide whether the control is enabled and to explain why it is disabled.

• For Editorial Workflows in Sanity Studio, use the Studio plugin. It provides the ready-made editor and workflow interfaces.
• Use @sanity/workflow-studio for a custom Studio integration such as a Document Action, dialog, tool, pane, or input.
• Use @sanity/workflow-sdk in an App SDK application. See App SDK for setup and resource routing.
• Use @sanity/workflow-react only when building a new store adapter. See Custom reactive adapters for the observer contract.

The hook returns the current reactive state and commands for previewing or committing changes:

• App SDK: build a custom workflow interface on the App SDK adapter.
• Custom reactive adapters: implement the observer contract for another store.
• API reference: inspect the complete session and adapter APIs.