Excalidraw Is More Than a Canvas

Excalidraw is the subject of this series, and the question is larger than how a browser draws a rectangle with a hand-written edge. The project combines an embeddable React editor, a full web application, an open drawing format, browser persistence, and encrypted collaboration. Understanding how those parts fit together gives readers a practical way to judge what Excalidraw is, what it can be integrated to do, and which responsibilities still belong to the host application.

The central idea is that Excalidraw treats a drawing as a structured visual document. The screen is one projection of that document. A saved .excalidraw file is another. Browser storage, image data, collaborative updates, and an embedding API are further projections or boundaries around the same underlying scene. That design is why the project can feel like a simple whiteboard while also behaving like a document system.

The apparent canvas is two related products

The first boundary is between the published @excalidraw/excalidraw package and the application hosted at excalidraw.com. The package is a React component that another application can render. Its core job is to provide the editor: a canvas-based workspace, drawing tools, text, arrows, images, libraries, selection, zooming, undo and redo, and export-related APIs. A host can supply initial data, observe changes, add interface elements, and control the editor through an imperative API.

The hosted application uses that core but adds responsibilities that do not automatically follow from embedding the component. Its repository area contains browser autosave, IndexedDB file handling, real-time collaboration, Firebase-backed room persistence, shareable links, and the application’s encryption flow. Those capabilities are part of a product built around the editor, not a silent promise that every application importing the React package receives the same storage and network behavior.

This distinction matters because the word “Excalidraw” can refer to a visual language, a component library, or a complete service experience. They overlap, but their ownership boundaries differ. If a team embeds the package in a knowledge base, design tool, or internal workflow, the host decides where documents are stored, how users are authenticated, whether collaboration is needed, and which surrounding UI is shown. If someone uses the hosted app, those decisions are already assembled into a particular browser application and deployment path.

The project’s own feature split makes the difference visible. The editor is presented as an open-source, infinite canvas with a hand-drawn style, image and library support, localization, and export formats. The hosted app is separately described as a progressive web application with offline behavior, real-time collaboration, end-to-end encryption, local-first browser saving, and shareable links. A reliable explanation must keep those claims attached to the layer that implements them.

One scene, several projections

A canvas widget usually suggests that the important state is the current picture on the screen. Excalidraw’s code points to a different center of gravity. Its durable drawing is a collection of elements: shapes, text, lines, arrows, free-drawn paths, images, frames, embeds, and other supported records. An element contains more than position and color. It may carry a stable identity, dimensions, rotation, style, grouping, frame membership, links, bindings to another element, ordering information, and version metadata.

That extra structure is not needless bookkeeping. An arrow attached to a rectangle is different from two unrelated strokes that happen to touch. Text inside a shape is different from text painted on top of it. An image on the canvas is represented by an element that refers to a separate binary file. A document therefore has relationships that a screenshot cannot preserve. The scene can be rendered again, restored after import, reordered, exported, or reconciled with another user’s version because its meaning is represented explicitly.

The scene is not the whole application state. AppState includes concerns such as the viewport, zoom, selection, active tool, dialogs, and other editor conditions. Those values affect what a particular person sees or is doing, but they are not generally part of the shared drawing in the same way as an element. Binary image data is separate again: the scene can say which file an image needs without forcing every scene operation to carry the image bytes inline.

Consider a small diagram with a box, a label inside it, an arrow connected to its edge, and an image placed nearby. The box and label need a relationship so the label can move with the container. The arrow needs a binding that can survive the box being resized or rotated. The image needs a file identifier and a status while its pixels are fetched or saved. The user’s zoom and selected tool should not become part of the diagram at all. A screenshot shows the final arrangement, but it cannot tell a later editor which text is attached to which shape, which endpoint should follow a boundary, or whether a missing image is a document problem or a storage problem. The structured scene can preserve those distinctions.

This separation lets one document serve different consumers. The interactive editor can draw the scene and add selection handles without saving those handles as content. An export routine can produce PNG or SVG output while preserving the option to embed a scene payload for later recovery. Browser persistence can save structured state and binary files through different storage mechanisms. Collaboration can exchange versioned elements rather than repeatedly sending a bitmap of the entire canvas. The host application can listen for changes or update the scene without owning the renderer’s internal representation.

flowchart LR H["Host application"] --> E["Embedded Excalidraw editor"] E --> S["Structured scene"] E --> A["Editor and viewport state"] S --> R["Rendered editor"] A --> R S --> X["Portable export"] S --> L["Local browser state"] S --> C["Encrypted collaboration"] S --> B["Binary file references"] B --> L B --> C R --> E L --> E C --> E

The diagram is deliberately not a component map. It is a data-flow model. The structured scene is the hub, while editor state changes the current projection and binary files follow a related but separate lifecycle. The arrows also run back toward the editor: imports, local restoration, and remote collaboration all return data to the scene before the user sees the result.

This model also explains why the project can add features without making each feature invent its own document representation. An export function can ask the scene for elements and files. A collaboration path can transmit versions of those elements. A library can package reusable elements. A host can initialize the same scene and then subscribe to changes. Each boundary still has its own policy, but the boundaries meet at a shared vocabulary. That is a stronger form of extensibility than adding buttons around an opaque bitmap, because the surrounding system can reason about what it is receiving and changing.

Why this architecture matters

The first consequence is interoperability. A drawing represented only as pixels can be displayed almost anywhere, but it is difficult to edit as a drawing. A structured scene can preserve relationships, restore text and arrows, attach images, and produce different outputs. Excalidraw’s open JSON envelope, library files, SVG export, and package-level restore and serialization functions all depend on the same idea: the document should remain meaningful outside one live browser view.

The second consequence is continuity. A user can leave a browser tab, reopen a local drawing, import a file, or join a room without asking the renderer to reverse-engineer a screenshot. In the hosted application, structured elements and editor state are saved locally while binary files use a separate IndexedDB-backed path. That is a concrete local-first design, but it still has browser quotas, scheduling, visibility, and file-status boundaries. “Saved locally” does not mean that every write is instantaneous or that every image is already retrievable.

The third consequence is collaboration. Multiple users do not need to stream the pixels generated by each other’s canvases. They can exchange structured element updates with identity, version, and ordering metadata, then render the resulting scene locally. The hosted application encrypts its collaboration payloads on the client side in the observed path, but the privacy claim still depends on the browser-delivered client, key handling, metadata, and deployment threat model. A structured protocol makes collaboration possible; it does not remove the need to reason about conflicts or operational failure.

The fourth consequence is extensibility. A host can treat Excalidraw as a visual editor embedded inside a larger product rather than as a page that must be surrendered to a complete whiteboard service. Initial data, change callbacks, imperative scene updates, custom UI, libraries, custom tools, and export hooks let the host decide how the editor participates in its own workflow. At the same time, the client-only rendering boundary matters in SSR frameworks: a browser canvas and DOM surface must be mounted in a browser-aware way, and a container with no height can produce a blank result even when the scene itself is valid.

That boundary changes the integration question. A host that only needs an editor may use the package and store the returned scene in its own document system. A host that needs the hosted app’s collaboration experience must either use that application path or provide equivalent ownership for identity, room membership, transport, persistence, file handling, and recovery. The fact that the same scene can cross those boundaries does not mean the boundaries disappear. It means they can be designed around a stable document contract.

These benefits come with a corresponding discipline. The scene model is powerful because it is shared, but shared models create compatibility obligations. Element fields must be normalized when older or hand-edited files are restored. Image references must be kept consistent with binary storage. Rendering must distinguish durable content from temporary overlays. Collaboration must choose what happens when two edits compete. A host must decide which parts of persistence, identity, access control, and recovery it owns rather than assuming the component answers them automatically.

The repository also gives reasons to resist easy adjectives. The code shows a browser persistence pipeline, not a transactionally durable database. It shows client-side encryption and encrypted room storage in the hosted application path, not a complete security audit. It shows cache limits and alternate export paths, not a universal performance number. These are not weaknesses to hide; they are the conditions under which the design should be understood. A system model is useful precisely because it makes ownership and failure visible.

That is the practical judgment this series develops. Excalidraw is not best understood as a collection of drawing buttons, nor as a server that happens to show a canvas. It is a structured visual-document engine wrapped in different product boundaries. Its hand-drawn appearance is a rendering choice over structured records. Its portability is a consequence of explicit document data. Its local-first behavior and encrypted collaboration are application lifecycles built around that data. Its embeddability is a contract that lets another product own the surrounding decisions.

The next step is to examine the scene itself: what an element contains, how elements express relationships, and why identity, ordering, and versioned change are necessary before rendering, persistence, or collaboration can be understood.

References