Excalidraw: An Embeddable Hand-Drawn Whiteboard for React Apps

What Excalidraw Solves and Who It Is For

Excalidraw solves a narrow but common problem: giving users a freehand sketching surface that produces clean, hand-drawn looking diagrams without requiring design skill. It is for developers building React applications that need an embedded whiteboard, such as diagramming tools, note-taking apps, or planning interfaces. The hosted site excalidraw.com is a minimal showcase of what the package can do, not the product itself. The repository is the source for both the npm package and the hosted app, which means you can see exactly how the showcase is built. The target user is a frontend engineer who wants a canvas with shapes, arrows, and free-drawing, and who is willing to integrate a third-party component rather than build one from scratch.

The Core Mechanism: A Canvas with a Hand-Drawn Renderer

The package is a React component that renders an infinite, canvas-based whiteboard. The hand-drawn style is applied to every shape, including rectangles, circles, diamonds, arrows, and lines. The canvas supports zoom and panning, which are essential for an infinite surface. The data model is an open format: drawings export as a .excalidraw JSON file. This is a key architectural point. The JSON is the source of truth, so you can save, load, and share drawings outside the app. The package also supports image insertion, shape libraries, and localization, which are all features you would expect from a mature editor.

Getting It Running: Installation and Integration

Installation is straightforward for a React project. The README gives two commands. With npm: npm install react react-dom @excalidraw/excalidraw. With yarn: yarn add react react-dom @excalidraw/excalidraw. The install command includes react and react-dom alongside the package. After installation, you import the component and render it. The README does not show a code example, but the documentation at docs.excalidraw.com covers the integration details. The package is published on npm under the scoped name @excalidraw/excalidraw. For running the repository locally for development, the README points to a separate Development Guide, which is not included in the README. That separation is worth noting: the npm package is the integration path, while the repo's excalidraw-app directory contains the hosted app's source.

The Hosted App vs. The npm Package: A Feature Gap

The hosted app at excalidraw.com includes features that the npm package does not yet have. Those features are real-time collaboration, end-to-end encryption, local-first autosave to the browser, and shareable readonly links. The README states that these will be added as drop-in plugins for the npm package in the future. That is a clear limitation for anyone embedding the package today. If you need multi-user editing, you cannot get it from the package right now. You would have to build your own collaboration layer on top of the JSON format, which is a significant engineering effort. This gap is the single most important factor when deciding whether to adopt the package.

Limitations and Failure Modes

The most obvious limitation is the missing collaboration features in the npm package. The README says they are coming, but there is no timeline. Another limitation is the hand-drawn style itself. It is the project's identity, but it is also a constraint. If your product needs precise, technical diagrams with straight lines and exact angles, Excalidraw will fight you. The README lists the editor as customizable and the .excalidraw JSON format as open. You need to check whether your backend can store and parse that format, or whether you need to convert it to something else. The package is React-only, so it is the wrong tool for a non-React frontend. Finally, the README lists a wide range of tools, but it does not mention any advanced features like layers, grouping, or alignment guides. Those may exist, but the README does not confirm them, so you should verify before assuming.

Alternatives and Their Different Approaches

The main alternative is to build a whiteboard from scratch using a canvas library like Fabric.js or Konva. That approach gives you full control over rendering and interaction, but it requires you to implement every tool, the undo/redo stack, and the export format yourself. Excalidraw gives you all of that out of the box. Another alternative is to use a diagramming tool like Mermaid, which generates diagrams from text. Mermaid is not a whiteboard; it is a declarative syntax that renders to SVG. That is a different approach entirely: you type a description, and the diagram is generated. Excalidraw is freehand. The choice depends on whether your users need to sketch freely or just display a structured diagram. A third alternative is to use a commercial whiteboard SDK. The key difference is that Excalidraw is free, open source, and MIT-licensed, while commercial SDKs may have licensing costs.

Maintenance, Upgrades, and License Implications

The repository is actively maintained. The last push was on 2026-11-02, and version 0.18.1 was released earlier, on 2026-04-21. Version 0.18.0 came in March 2025, and 0.17.3 in February 2024. Releases are infrequent compared with pushes, so the npm package can lag behind the repository. The package is pre-1.0, so the API may change. The license is MIT, which is permissive. You can use it in commercial products, modify it, and distribute it, as long as you include the original copyright notice. This is a low-license-friction choice for most companies. The README mentions that the hosted app features will become plugins, so you should watch for those releases if you need collaboration. Upgrading the package may require adjusting to new component props or rendering behavior, so read the changelog before each update. The README also points to Excalidraw+ and Open Collective sponsorship.

Editorial conclusion

Adopt Excalidraw if you need a free, embeddable whiteboard for React and can accept that real-time collaboration and end-to-end encryption are not yet in the npm package. Do not adopt it if your product requires multi-user editing out of the box or if you need a non-hand-drawn aesthetic. Before committing, verify the current state of the package's plugin roadmap, test the .excalidraw JSON format against your data needs, and confirm that the hand-drawn style fits your brand.

Frequently asked questions

Official sources

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