feat(PrismicToolbar): add onPreviewUpdate and onPreviewEnd props (#249)

* feat: add onPreviewUpdate and onPreviewEnd callback props to PrismicToolbar

Allows users to handle preview lifecycle events without manual useEffect
and AbortController boilerplate.

Closes #248

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: fix onPreviewUpdate JSDoc description

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: update TSDocs

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: angeloashmore

e2e-projects/nextjs/app/PrismicToolbar/preview-events/PrismicToolbarPreviewEvents.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import { type ReactNode, useState } from "react";
+import { PrismicToolbar } from "@prismicio/react";
+
+export function PrismicToolbarPreviewEvents(props: {
+	repositoryName: string;
+}): ReactNode {
+	const [updateCount, setUpdateCount] = useState(0);
+	const [endCount, setEndCount] = useState(0);
+	const [updateRef, setUpdateRef] = useState<string>("");
+
+	return (
+		<>
+			<PrismicToolbar
+				repositoryName={props.repositoryName}
+				onPreviewUpdate={(event) => {
+					setUpdateCount((c) => c + 1);
+					setUpdateRef(event.detail.ref);
+				}}
+				onPreviewEnd={() => setEndCount((c) => c + 1)}
+			/>
+			<span data-testid="update-count">{updateCount}</span>
+			<span data-testid="end-count">{endCount}</span>
+			<span data-testid="update-ref">{updateRef}</span>
+		</>
+	);
+}

e2e-projects/nextjs/app/PrismicToolbar/preview-events/page.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+
+import { createClient } from "@/prismicio";
+import { PrismicToolbarPreviewEvents } from "./PrismicToolbarPreviewEvents";
+
+export default async function Page(): Promise<ReactNode> {
+	const client = await createClient();
+
+	return (
+		<PrismicToolbarPreviewEvents repositoryName={client.repositoryName} />
+	);
+}

src/PrismicToolbar.tsx

@@ -1,7 +1,7 @@
 "use client";
 
-import { type FC, useEffect } from "react";
 import { getToolbarSrc } from "@prismicio/client";
+import { type FC, useEffect, useRef } from "react";
 
 /** Props for `<PrismicToolbar>`. */
 export type PrismicToolbarProps = {
@@ -10,6 +10,26 @@ export type PrismicToolbarProps = {
 	 * repository URL is `my-repo.prismic.io`.
 	 */
 	repositoryName: string;
+
+	/**
+	 * Called when the Prismic toolbar triggers a preview update. This happens
+	 * when the previewed content changes.
+	 *
+	 * The new ref can be read from `event.detail.ref`.
+	 *
+	 * The default page reload behavior can be cancelled with
+	 * `event.preventDefault()`.
+	 */
+	onPreviewUpdate?: (event: CustomEvent<{ ref: string }>) => void;
+
+	/**
+	 * Called when the Prismic toolbar triggers a preview end. This happens when
+	 * a preview session is closed.
+	 *
+	 * The default page reload behavior can be cancelled with
+	 * `event.preventDefault()`.
+	 */
+	onPreviewEnd?: (event: CustomEvent<null>) => void;
 };
 
 /**
@@ -24,10 +44,16 @@ export type PrismicToolbarProps = {
  * @see Learn how to set up preview functionality and the toolbar's role in preview sessions: {@link https://prismic.io/docs/previews}
  */
 export const PrismicToolbar: FC<PrismicToolbarProps> = (props) => {
-	const { repositoryName } = props;
+	const { repositoryName, onPreviewUpdate, onPreviewEnd } = props;
 
 	const src = getToolbarSrc(repositoryName);
 
+	const onPreviewUpdateRef = useRef(onPreviewUpdate);
+	onPreviewUpdateRef.current = onPreviewUpdate;
+
+	const onPreviewEndRef = useRef(onPreviewEnd);
+	onPreviewEndRef.current = onPreviewEnd;
+
 	useEffect(() => {
 		const existingScript = document.querySelector(`script[src="${src}"]`);
 
@@ -48,5 +74,24 @@ export const PrismicToolbar: FC<PrismicToolbarProps> = (props) => {
 		}
 	}, [repositoryName, src]);
 
+	useEffect(() => {
+		const controller = new AbortController();
+
+		window.addEventListener(
+			"prismicPreviewUpdate",
+			(event) =>
+				onPreviewUpdateRef.current?.(event as CustomEvent<{ ref: string }>),
+			{ signal: controller.signal },
+		);
+
+		window.addEventListener(
+			"prismicPreviewEnd",
+			(event) => onPreviewEndRef.current?.(event as CustomEvent<null>),
+			{ signal: controller.signal },
+		);
+
+		return () => controller.abort();
+	}, []);
+
 	return null;
 };

tests/PrismicToolbar.spec.ts

@@ -16,3 +16,56 @@ test("includes the repository name in the script element", async ({
 		appPage.repository.domain,
 	);
 });
+
+test("calls onPreviewUpdate when prismicPreviewUpdate is dispatched", async ({
+	page,
+}) => {
+	await page.goto("/PrismicToolbar/preview-events");
+
+	const updateCount = page.getByTestId("update-count");
+	const updateRef = page.getByTestId("update-ref");
+	await expect(updateCount).toHaveText("0");
+
+	await page.evaluate(() => {
+		window.dispatchEvent(
+			new CustomEvent("prismicPreviewUpdate", {
+				detail: { ref: "test-ref-1" },
+			}),
+		);
+	});
+	await expect(updateCount).toHaveText("1");
+	await expect(updateRef).toHaveText("test-ref-1");
+
+	await page.evaluate(() => {
+		window.dispatchEvent(
+			new CustomEvent("prismicPreviewUpdate", {
+				detail: { ref: "test-ref-2" },
+			}),
+		);
+	});
+	await expect(updateCount).toHaveText("2");
+	await expect(updateRef).toHaveText("test-ref-2");
+});
+
+test("calls onPreviewEnd when prismicPreviewEnd is dispatched", async ({
+	page,
+}) => {
+	await page.goto("/PrismicToolbar/preview-events");
+
+	const endCount = page.getByTestId("end-count");
+	await expect(endCount).toHaveText("0");
+
+	await page.evaluate(() => {
+		window.dispatchEvent(
+			new CustomEvent("prismicPreviewEnd", { detail: null }),
+		);
+	});
+	await expect(endCount).toHaveText("1");
+
+	await page.evaluate(() => {
+		window.dispatchEvent(
+			new CustomEvent("prismicPreviewEnd", { detail: null }),
+		);
+	});
+	await expect(endCount).toHaveText("2");
+});