Presenting and previewing content

By presenting all in-flight changes together within the real experience, content creators, reviewers, and stakeholders can get a realistic view of what the experience will look like when these changes are published. High-fidelity content previews enable valuable and accurate feedback, validation, and approvals before rolling out updates.

Likewise, ensuring that your "production" or "public" experience or application only presents published content is critical to ensuring that what is presented to your consumers is complete, validated, and approved.

Sanity offers a range of tools and Perspectives for Content Lake to help you build first-class preview experiences.

A key feature of composable content is that you can shape data from a variety of independent but interconnected documents into whatever shape is required on the consuming end. For content authored in Sanity Studio, all unpublished changes are tracked in draft documents that co-exist with the published version of the same document. With content spread over multiple documents, each with its own publishing state, creating robust preview tooling can become cumbersome.

Perspectives is an out-of-the-box solution that does away with the heavy lifting of creating engaging preview experiences.

Perspectives let you run your queries against an alternate "view" of the documents in your dataset. Use the previewDrafts perspective to preview what your content would look like if all drafts and changes were published, or set the published perspective in your production environment to make sure no unfinished draft content is accidentally made public.

The perspective is set as a property of the Sanity client configuration or passed as a parameter to the HTTP API query endpoints, allowing you to reuse queries between preview and production environments.

Web applications often use perspectives to retrieve initial server-side or static content.

• In your production environment, queries use the published perspective.
• In preview environments, queries use the previewDrafts perspective and are then hydrated with live updates via Loaders.

// Example JS/TS client configuration
import {createClient} from '@sanity/client'

const client = createClient({
  ...config,
  useCdn: false, // must be false for 'previewDrafts'
  perspective: 'previewDrafts', // 'raw' | 'published' | 'previewDrafts' 
})

// Example using HTTP API
/data/query/production?query=*[]&perspective=previewDrafts

The default behavior of the client, which you can set explicitly by specifying the raw perspective, is to return both drafts and published content for authenticated requests. This perspective is assumed if no value is set for the perspective property.

When using this perspective, your queries will return as if all draft documents in your dataset were published. This means:

• References to draft documents will be resolved/dereferenced normally, exactly as when dereferencing published documents
• Query results will not be cached in the CDN, ensuring you always get the latest most up-to-date version of in-flight changes
• When using custom permission resources, draft documents will be presented only when the user’s permissions grant access to the draft document; otherwise, the published version is presented

When you use this perspective, your queries will operate as if there were no draft documents in your dataset, i.e. no draft document will ever be returned.

The Perspectives feature alone can enable running independent preview and production environments, but for truly custom, interactive live-as-you-type preview, Sanity also offers powerful tooling for any front end framework and offers guides on the most popular ones.

If, for some reason, you want to filter documents based on their draft status without using perspectives, you can check the documents _id for the drafts. path segment. Note that this query only makes sense when using the default (raw) perspective, since previewDrafts and published will return no documents with drafts. in their path.

[!(_id in path('drafts.**'))] // _id matches anything that is not in the drafts-path