Visual Editing with Next.js Pages Router
Get started with Sanity Visual Editing in a new or existing Next.js application using the Pages Router.
Following this guide will enable you to:
- Render overlays in your application, allowing content editors to jump directly from Sanity content to its source in Sanity Studio.
- Edit your content and see changes reflected in an embedded preview of your application in Sanity’s Presentation Tool.
- Provide instant updates and seamless switching between draft and published content.
Gotcha
This guide is for the Next.js Pages Router. See the guide for the Next.js App Router.
Prerequisites
- A Sanity project with a hosted or embedded Studio.
- A Next.js application using Pages Router. Follow this guide to set one up.
Next.js application setup
The following steps should be performed in your Next.js application.
Install dependencies
Install the dependencies that will provide your application with data fetching and Visual Editing capabilities.
npm install next-sanity @sanity/visual-editing @sanity/react-loader @sanity/preview-url-secret
pnpm add next-sanity @sanity/visual-editing @sanity/react-loader @sanity/preview-url-secret
yarn add next-sanity @sanity/visual-editing @sanity/react-loader @sanity/preview-url-secret
bun add next-sanity @sanity/visual-editing @sanity/react-loader @sanity/preview-url-secret
Add environment variables
Create a .env file in your application’s root directory to provide Sanity-specific configuration.
You can use Manage to find your project ID and dataset, and to create a token with Viewer permissions which will be used to fetch preview content.
The URL of your Sanity Studio will depend on where it is hosted or embedded.
# Public NEXT_PUBLIC_SANITY_PROJECT_ID="YOUR_PROJECT_ID" NEXT_PUBLIC_SANITY_DATASET="YOUR_DATASET" NEXT_PUBLIC_SANITY_STUDIO_URL="YOUR_STUDIO_URL" # Private SANITY_VIEWER_TOKEN="YOUR_VIEWER_TOKEN"
Application setup
Configure the Sanity client
Create a Sanity client instance to handle fetching data from Content Lake.
Configuring the stega option enables automatic overlays for basic data types when preview mode is enabled. You can read more about how stega works.
import { createClient } from "next-sanity";
export const client = createClient({
projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID,
dataset: process.env.NEXT_PUBLIC_SANITY_DATASET,
apiVersion: "2026-07-01",
useCdn: true,
token: process.env.SANITY_VIEWER_TOKEN,
stega: {
studioUrl: process.env.NEXT_PUBLIC_SANITY_STUDIO_URL,
},
});Draft mode
Draft mode allows authorized content editors to view and interact with draft content. Presentation Tool and sharing communicate with your Next.js app to enable or disable draft mode.
Create an API endpoint (in src/pages/api) to enable draft mode when viewing your application in Presentation Tool.
import type { NextApiRequest, NextApiResponse } from "next";
import { validatePreviewUrl } from "@sanity/preview-url-secret";
import { client } from "@/sanity/client";
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
if (!req.url) {
return res.status(500).json({ message: "Missing request URL" });
}
const { isValid, redirectTo = "/" } = await validatePreviewUrl(
client.withConfig({
token: process.env.SANITY_VIEWER_TOKEN,
}),
req.url
);
if (!isValid) {
return res.status(401).json({ message: "Invalid secret" });
}
// Enable Draft Mode
res.setDraftMode({ enable: true });
res.writeHead(307, { Location: redirectTo });
res.end();
}Similarly, create an API endpoint to disable draft mode.
import type { NextApiRequest, NextApiResponse } from 'next'
export default function handle(
_req: NextApiRequest,
res: NextApiResponse<void>,
): void {
// Exit the current user from "Draft Mode".
res.setDraftMode({ enable: false })
// Redirect the user back to the index page.
res.writeHead(307, { Location: '/' })
res.end()
}Create a new component with a link to the disable endpoint. We add conditional logic to only render this for content authors when viewing draft content in a non-Presentation context. The code in this example uses minimal styling, but you may wish to create a more suitable banner that fits your layout.
import { useEffect, useState } from "react";
export function DisableDraftMode() {
const [show, setShow] = useState(false);
useEffect(() => {
setShow(window.top === window);
}, []);
return show && <a href={"/api/disable-draft"}>Disable Draft Mode</a>;
}Enable Visual Editing
Create a Visual Editing wrapper component.
The <VisualEditing> component handles rendering overlays, enabling click to edit, and refreshing pages in your application when content changes. Render it alongside the <DisableDraftMode> component you created above.
Embedded studios
The approach below adds the VisualEditing components to the App layout. If you’re using an embedded studio (one that renders on a route in your Next.js app), you should only include VisualEditing components in your content layouts.
Our recommendation is that you create dedicated layout components for your content and studio routes.
We provide a basic refresh mechanism that will reload the page when changes are made in Presentation Tool. You can optionally use loaders to provide seamless updates.
import { VisualEditing } from "@sanity/visual-editing/next-pages-router";
import { useLiveMode } from "@sanity/react-loader";
import { DisableDraftMode } from "@/components/DisableDraftMode";
import { client } from "@/sanity/client";
const stegaClient = client.withConfig({ stega: true });
export default function SanityVisualEditing() {
useLiveMode({ client: stegaClient });
return (
<>
<VisualEditing />
<DisableDraftMode />
</>
);
}<VisualEditing /> props
The <VisualEditing /> component accepts the following optional props introduced in @sanity/visual-editing 5.5.0.
keepStegaOnCopy (boolean, optional)
Default: false. By default, <VisualEditing /> intercepts copy events and automatically strips stega encoding from both text/plain and text/html clipboard payloads. This ensures that users copying text from the preview page do not get invisible stega characters in their clipboard. Pass keepStegaOnCopy to opt out of this behavior and preserve stega encoding in clipboard output.
onSuspiciousStega (callback, optional)
An opt-in callback that reports stega encoding found in unsafe DOM placements. When provided, <VisualEditing /> audits the DOM for stega in locations where it should not appear, including:
- Element attributes such as
class,id,href,src,style,data-*, and others - Inside
<head>:title,meta[content], and JSON-LD script blocks - Text content inside
<script>or<style>elements - Textarea form values
- The page URL
Each report includes the kind, element, attribute (if applicable), value, cleaned, and sanity (decoded edit information).
<VisualEditing
onSuspiciousStega={(reports) => {
for (const report of reports) {
console.warn(`Stega found in ${report.kind}`, report)
}
}}
/>Development use
The onSuspiciousStega callback audits the DOM using TreeWalker and MutationObserver. We recommend using it in development and debugging contexts rather than in production.
In the root layout file, dynamically import and render the <SanityVisualEditing> wrapper component when draft mode is enabled.
import type { AppProps } from "next/app";
import dynamic from "next/dynamic";
const SanityVisualEditing = dynamic(() => import("@/components/SanityVisualEditing"));
export default function App({ Component, pageProps }: AppProps) {
const { draftMode } = pageProps;
return (
<>
<Component {...pageProps} />
{draftMode && <SanityVisualEditing />}
</>
);
}Set up loaders
Create a new file to configure loaders. Call setServerClient, with the client instance which should be used to fetch data on the server.
We also create a helper function to return fetch options based on the draft mode state, and export this alongside loadQuery for convenience.
import * as serverOnly from "@sanity/react-loader";
import { client } from "./client";
import { ClientPerspective } from "next-sanity";
const { loadQuery, setServerClient } = serverOnly;
setServerClient(
client.withConfig({
token: process.env.SANITY_VIEWER_TOKEN,
})
);
const loadQueryOptions = (context: { draftMode?: boolean }) => {
const { draftMode } = context;
return draftMode
? {
// At this time, this approach does not support dynamically
// pulling in the Studio perspective, so you must hard-code the value
// or retrieve it from the cookie manually.
perspective: "drafts" as ClientPerspective,
stega: true,
useCdn: false,
}
: {};
};
export { loadQuery, loadQueryOptions };Render a page in preview mode
In getStaticProps use the loadQuery function created above. The initial data returned here is passed to useQuery in the page component.
When in Presentation Tool, useQuery will handle live updates as content is edited.
import { loadQuery, loadQueryOptions } from "@/sanity/ssr";
import { useQuery } from "@sanity/react-loader";
import type { GetStaticProps, InferGetStaticPropsType } from "next";
const query = `*[_type == "page"][0]{title}`;
export const getStaticProps = (async (context) => {
const { draftMode = false } = context;
const options = loadQueryOptions({ draftMode });
const initial = await loadQuery<{ title?: string }>(query, {}, options);
return { props: { initial, draftMode } };
}) satisfies GetStaticProps;
export type PageProps = InferGetStaticPropsType<typeof getStaticProps>;
export default function Page(props: PageProps) {
const { initial } = props;
const { data } = useQuery(query, {}, { initial });
return <h1>{data.title}</h1>;
}Studio setup
To set up Presentation Tool in your Sanity Studio, import the tool from sanity/presentation, add it to your plugins array, and set previewUrl to the base URL of your application.
We similarly recommend using environment variables loaded via a .env file to support development and production environments.
import { defineConfig } from "sanity";
import { presentationTool } from "sanity/presentation";
export default defineConfig({
// ... project configuration
plugins: [
presentationTool({
previewUrl: {
// Add a new ENV var to your Studio codebase if needed to accommodate live vs local preview.
initial: process.env.SANITY_STUDIO_PREVIEW_ORIGIN || 'http://localhost:3000',
previewMode: {
enable: "/api/enable-draft",
},
},
}),
// ... other plugins
],
});Optional extras
Add data attributes for overlays
useQuery also returns an encodeDataAttribute helper method for generating data-sanity attributes. These attributes give you direct control over rendering overlays in your application, and are especially useful if not using stega encoding.
import { loadQuery, loadQueryOptions } from "@/sanity/ssr";
import { useQuery } from "@sanity/react-loader";
import type { GetStaticProps, InferGetStaticPropsType } from "next";
const query = `*[_type == "page"][0]{title}`;
export const getStaticProps = (async (context) => {
const options = loadQueryOptions(context);
const initial = await loadQuery<{ title?: string }>(query, {}, options);
return { props: { initial } };
}) satisfies GetStaticProps;
export type PageProps = InferGetStaticPropsType<typeof getStaticProps>;
export default function Page(props: PageProps) {
const { initial } = props;
const { data, encodeDataAttribute } = useQuery(query, {}, { initial });
return <h1 data-sanity={encodeDataAttribute(["title"])}>{data.title}</h1>;
}Next steps
You now have a Next.js Pages Router application with click-to-edit overlays, live updates in Presentation Tool, and draft mode switching. To go deeper, learn how stega encoding works or take direct control of overlays in your application.