Integrate with Next.js and browser environments
Load Excalidraw safely in Next.js, Preact, and a browser page.
Use client-only loading when you embed Excalidraw in a framework that renders on the server. This guide shows the supported pattern for Next.js, the build setting required by Preact, and the basic browser setup.
Before you begin
Install react, react-dom, and @excalidraw/excalidraw. Your host element must have non-zero width and height because Excalidraw fills its containing block. React 17, 18, and 19 are peer-compatible according to the integration guidance.
The diagram shows the important boundary: server-rendered routes must defer the component until the browser, while direct browser and client-only applications can import it normally.
Load Excalidraw in Next.js
For the App Router, mark the wrapper as a client component and import the CSS with the component. Keep utility imports in this wrapper when you need them.
"use client";
import { Excalidraw, convertToExcalidrawElements } from "@excalidraw/excalidraw";
import "@excalidraw/excalidraw/index.css";
export default function ExcalidrawWrapper() {
return (
<div style={{ height: 500, width: 500 }}>
<Excalidraw />
</div>
);
}The wrapper is browser-only and provides a visible canvas area.
In the route, load the wrapper with ssr: false.
import dynamic from "next/dynamic";
const ExcalidrawWrapper = dynamic(
() => import("../excalidrawWrapper"),
{ ssr: false },
);
export default function Page() {
return <ExcalidrawWrapper />;
}The route no longer attempts to render the editor during server-side rendering.
Set both dimensions on the containing block, or use a class with equivalent rules.
.excalidraw-container {
height: 500px;
width: 100%;
}The editor occupies the container instead of collapsing into an empty or invisible area.
If you copied the package fonts to your public assets, set window.EXCALIDRAW_ASSET_PATH to that same path before the editor loads.
<Script id="excalidraw-assets" strategy="beforeInteractive">
{`window.EXCALIDRAW_ASSET_PATH = "/";`}
</Script>Fonts and other package assets resolve from the configured location.
Use Preact or a browser page
For Preact, set process.env.IS_PREACT to true and make that value available in your build. Vite removes environment variables by default, so define the value explicitly in the Vite configuration.
For a direct browser integration, load the package CSS, provide React and React DOM through an import map, set EXCALIDRAW_ASSET_PATH if needed, and mount into an element such as <div id="app"></div>. Use the package’s browser build rather than importing server-side code.
Troubleshoot common failures
Next steps
Continue with customize embedded UI and render props or review Excalidraw component props and configuration.