Embed and integrate

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

Create a client wrapper

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.

tsx

"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.

Dynamically import the wrapper

In the route, load the wrapper with ssr: false.

tsx

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.

Give the container dimensions

Set both dimensions on the containing block, or use a class with equivalent rules.

css

.excalidraw-container {
  height: 500px;
  width: 100%;
}

The editor occupies the container instead of collapsing into an empty or invisible area.

Set the asset path when self-hosting

If you copied the package fonts to your public assets, set window.EXCALIDRAW_ASSET_PATH to that same path before the editor loads.

tsx

<Script id="excalidraw-assets" strategy="beforeInteractive">
  {`window.EXCALIDRAW_ASSET_PATH = "/";`}
</Script>

Fonts and other package assets resolve from the configured location.

✅Verify the route in a browser: the canvas renders without a server-rendering error and occupies the dimensions of its container.

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.