Interact with the Dashboard

Use App SDK hooks to read Dashboard state, navigate, and open panels from your app, panels, and tiles.

Your app, panels, and tiles can read from and act on the Dashboard they run in: the organization, the signed-in user, the color scheme, navigation, and panels. The App SDK provides this through hooks in @sanity/sdk-react/dashboard.

• @sanity/sdk-react 3.9.0 or later.
• An app configured with defineApplication, running under sanity dev or deployed with it. Apps deployed before Dashboard 2.0 run in an iframe and only support some hooks, such as useNavigate and useOrganizationId.

Hooks need an App SDK instance. In an app's window, SanityApp in App.tsx provides one. Panels and tiles each render in their own island, so wrap each panel component and tile in SanityApp, and any panel title that uses hooks:

import {SanityApp} from '@sanity/sdk-react'
import type {ReactNode} from 'react'

export function Providers({children}: {children: ReactNode}) {
  return (
    <SanityApp fallback={null}>
      {children}
    </SanityApp>
  )
}

Web workers don't run React, so they can't use these hooks. A worker gets bus from unstable_defineService instead, which reaches the Dashboard message bus and the app's own views.

Inside the Dashboard, SanityApp signs your app in with the Dashboard user's session. You don't need to add a login flow or handle tokens.

• useNavigate: Keep your app's router in sync with the Dashboard, and navigate anywhere in it.
• urlFor: Build Dashboard URLs for apps, Studio documents, Media Library, and Canvas.
• useNavigateToStudioDocument: Open a document in a Studio.
• useOrganizationId: Read the current organization's ID.
• useCurrentUser: Read the signed-in user.
• useApplications: List the organization's apps and their views.
• useTopic: Read Dashboard state, such as preferences.color-scheme or panels.mode.
• useEmit: Send a Dashboard event, such as panels.mode.set.
• useWorker: Post to one of your app's workers and listen to its messages.

These are the hooks most apps need. For every export, including types, URL builders, and the message bus, see the @sanity/sdk-react/dashboard reference at reference.sanity.io.

Most of these hooks throw when no Dashboard is present, for example when you open the app's own port directly instead of the Dashboard URL:

Cannot read topic "preferences.color-scheme" without an installed dashboard message bus

useOrganizationId returns undefined instead, and urlFor works anywhere.