Excalidraw: Open-Source Hand-Drawn Whiteboard for Diagrams and Wireframes

What Excalidraw Solves and Who It Is For

Technical diagrams produced by conventional vector tools tend to look polished in a way that signals finality. Excalidraw takes the opposite approach: every shape is rendered with a hand-drawn aesthetic that keeps diagrams clearly provisional and easy to update. The project targets engineers doing system design sketches, educators drawing concepts live, and product teams who want a shared visual scratch pad that does not require any account sign-up.

The repository ships two distinct things. The application hosted at excalidraw.com is a full collaboration tool with offline support via PWA. The npm package, @excalidraw/excalidraw, is a React component that any team can embed inside its own product. Google Cloud, Meta, CodeSandbox, Notion, and Replit are listed in the README as examples of integrators.

Architecture: Canvas, JSON Format, and the npm Package

The editor is built on an infinite HTML canvas. All drawing state serialises to a JSON file with the .excalidraw extension. That format is the persistence unit: users can open, share, and edit these files without any server. The React component is published as @excalidraw/excalidraw and is the only entry point for embedding.

The monorepo at the root of the repository is managed with Yarn workspaces. It contains the excalidraw-app directory, which is the source of excalidraw.com, and a packages/ directory with separate packages for the component, math, element handling, and other concerns. The package.json at the root lists Node 18 or higher as the engine requirement.

Installing and Embedding the npm Package

To embed Excalidraw in a React application, install the component along with its React peer dependencies:

npm install react react-dom @excalidraw/excalidraw

The README notes that yarn is equally supported:

yarn add react react-dom @excalidraw/excalidraw

After installation, import the Excalidraw component from the package and mount it inside a container element. The installation documentation at docs.excalidraw.com covers initialising the component with data, reading the scene state via an API, and configuring export options. The package exposes export utilities for PNG, SVG, and the .excalidraw JSON format.

Running Excalidraw with Docker

The repository includes a Dockerfile and a docker-compose.yml for running the full application locally. The compose file exposes port 3000 on the host and maps it to port 80 inside the container:

docker compose up

The Dockerfile builds the excalidraw-app using Node 24 in a build stage, then serves the resulting static files from nginx. The Docker path is primarily for local development or for teams that want a self-hosted instance of the web app rather than a dependency on the public excalidraw.com service.

Collaboration, Encryption, and the Hosted App

The hosted version at excalidraw.com adds features that are listed in the README as separate from the npm package: real-time collaboration, end-to-end encryption, shareable read-only links, and local-first autosave to the browser. Collaboration works through a generated room link. Because the content is end-to-end encrypted, the server that facilitates the connection cannot read the drawing data.

The README explicitly states these collaboration features are not yet available as drop-in plugins for the npm package, though the project notes they plan to add them. A team embedding the package today and needing multi-user collaboration must either build its own sync layer or use the hosted app.

Limitations and Cases Where Excalidraw Is the Wrong Tool

The hand-drawn style is a fixed aesthetic choice, not a theme that can be toggled off. Teams that need formal diagram notation, precise geometric alignment, or pixel-exact output for print or publication will find the style limiting. There is no built-in diagram-as-code path: shapes must be placed visually, not declared in a text format like Mermaid or Graphviz.

The npm package requires React. Projects built on Vue, Svelte, or vanilla JavaScript cannot use the component directly without a wrapper. The library's rich feature set also adds bundle weight: the package pulls in a significant set of dependencies that must be considered for applications where page load budget is constrained.

There is no database integration. Persistence is handled entirely in the browser through autosave to localStorage or by explicitly exporting the .excalidraw file. Teams that need drawings stored server-side and searchable must implement that layer themselves.

Alternative: Mermaid and the Difference in Approach

Mermaid is the most common alternative for teams already embedded in a text-based workflow. Mermaid diagrams are written as code in a domain-specific language and rendered to SVG, which makes them easy to version-control and generate programmatically. Excalidraw is the opposite: it is a direct-manipulation canvas where shapes are placed by hand and state is stored as structured JSON, not human-editable text.

The practical difference is that Mermaid fits documentation pipelines that produce diagrams from data, while Excalidraw fits collaborative sketching sessions and design explorations where the drawing process itself is the work. For system design interviews, architecture brainstorming, or quick wireframes shared in a meeting, Excalidraw's interactive canvas is faster. For automated diagram generation in CI pipelines or documentation sites, Mermaid is the more natural fit.

Maintenance, License, and Integration Ecosystem

The repository is not archived and the last push was on 2026-09-26. The v0.18.1 release was published on 2026-04-21. The project is licensed under MIT, which permits commercial embedding without royalty obligations.

Beyond the npm package, the README lists a VS Code extension published as pomdtr.excalidraw-editor on the Visual Studio Marketplace. The Obsidian Excalidraw plugin, maintained as a separate project by zsviczian, is also listed as an integration. These extensions each carry their own release cycles and their own dependency requirements, independent of this repository's versioning.

Editorial conclusion

Excalidraw fits engineers and designers who want a quick, visually informal diagramming tool that embeds cleanly into a React application or works offline as a PWA. It is not the right choice for teams that need formal UML notation, structured data exports, or a backend-driven diagram store. Before adopting the npm package, verify that your React version satisfies the peer dependency on react and react-dom, and review the docs.excalidraw.com API reference to confirm the component supports the export formats your workflow requires.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes