Excalidraw

Excalidraw is a free, open-source whiteboard that runs in the browser, built for the quick boxes-and-arrows diagrams developers draw to explain a system. There's no account and nothing to install: you open the page and start drawing.

What Excalidraw is for

Diagram tools tend to split into two kinds. Some are for finished, precise diagrams with exact alignment and standard symbols. Excalidraw is the other kind, for the thinking stage: explaining a service in a design review, or sketching a feature before anyone builds it.

It gives you an endless canvas and a small set of tools: rectangles, diamonds, ellipses, arrows, lines, a pencil for free drawing, text and images. With so little to choose from, you spend your time on the diagram rather than on the tool.

The code is open source under the MIT licence. The app at excalidraw.com is free, and a paid version, Excalidraw+, adds cloud workspaces for teams. The editor is also published as a React component (@excalidraw/excalidraw on npm), which is why you'll meet the same canvas inside other apps.

Drawing with the keyboard

Every tool has a one-key shortcut, and the shortcuts are what make Excalidraw fast. Press the key, then drag on the canvas:

Press ? in the app for the full list.

To label a shape, double-click it and type. The text belongs to the shape: it stays centred inside it and moves with it. Double-clicking an arrow labels the arrow the same way, and double-clicking an empty part of the canvas starts free-standing text.

Arrows that stay attached

When you draw an arrow from one shape to another, its ends bind to the shapes. Excalidraw highlights a shape as the arrow's end gets close; let go there and the arrow is attached. Move either shape later and the arrow follows, so the two stay connected.

Binding is what makes a whiteboard usable for system diagrams. Without it, rearranging boxes means redrawing every arrow by hand, which is when people stop keeping a diagram tidy.

An arrow you end in empty space isn't bound to anything. If moving a box leaves an arrow behind, drag the arrow's end back onto the box until it highlights.

A worked example: an online shop

Here is a four-box diagram of a small online shop, the kind you'd sketch to explain an order to a new teammate:

1. Press R and drag a box. Double-click it and type 'Customer'.
2. Do the same for 'Shop website', 'Orders API' and 'Stock database', stacked down the page.
3. Press A and drag from 'Customer' to 'Shop website', letting go when the second box highlights. Repeat down the stack.
4. Double-click the arrow between the API and the database and type 'checks stock'.
5. Drag 'Stock database' to one side. Its arrow follows.

There's a quicker way to grow a chain like this. With a box selected, press Ctrl and an arrow key (Cmd on a Mac): Excalidraw adds a new box in that direction, already joined to the first by an arrow. Repeat it to build a flowchart without reaching for the mouse.

Why it looks hand-drawn

Every shape comes out slightly wobbly, with a hand-written font, on purpose. A rough sketch tells the people looking at it that the design is still open. Nobody argues about alignment or font choice in a drawing that clearly isn't finished, so the discussion stays on the ideas.

Here is the style on a set of app wireframes:

When you need a cleaner result, the style panel's 'Sloppiness' setting straightens the lines, and the font can switch from 'Hand-drawn' to 'Normal' or 'Code'. For a polished diagram that follows a standard notation, though, a tool built for that job, such as draw.io or a dedicated UML editor, is the better fit.

Drawing together, privately

Click Share and start a live session to get a link. Anyone who opens it joins the same board and sees each change as it happens, with everyone's cursor on the canvas.

Live sessions and shared links are both end-to-end encrypted. Your browser creates a random key and encrypts the board before it leaves your machine. The key goes into the link, after the '#'. Browsers never send that part of a URL to a server, so Excalidraw's server only ever stores and relays data it can't read.

Here is a shared link, travelling from your browser to a friend's:

The other side of this design is that the link is the key. There are no per-person permissions: anyone who has the link can open the board. Share it the way you'd share a password, and start a fresh session rather than reusing an old link with people who no longer need access.

From Mermaid code to a diagram

If you already write diagrams as text, you don't have to draw at all. Mermaid is a small language for describing diagrams, and Excalidraw can turn it into shapes. Open 'More tools', choose 'Mermaid to Excalidraw', paste your code and insert the result.

The online shop from earlier, written in Mermaid:

flowchart TD
  C[Customer] --> W[Shop website]
  W --> A[Orders API]
  A -->|checks stock| D[Stock database]

A flowchart arrives as ordinary Excalidraw shapes and arrows, so you can drag, restyle and annotate it like anything you drew. Some other Mermaid diagram types convert too. A type the converter doesn't support is inserted as a single image, which you can't edit piece by piece.

This makes a good first draft: describe the structure in text, convert it, then rearrange it by hand into something easier to read than an automatic layout.

Saving and exporting your work

On excalidraw.com your board saves automatically, but only to your browser's local storage. It won't be there on another device or in another browser, and clearing your site data deletes it.

So export anything you want to keep. From the menu you can save:

• A PNG, for chat, slides and documents.
• An SVG, which stays sharp at any size and suits documentation sites.
• An .excalidraw file: plain JSON that opens again in Excalidraw with every shape still editable.

Image exports have an 'Embed scene' option. Tick it and the PNG or SVG carries the drawing's data inside it, so you can open the image in Excalidraw later and carry on editing. That suits diagrams in a README: the picture shows on GitHub, and the same file is the editable source.

Because .excalidraw files are text, you can commit them beside the code they describe. Changes do show up in diffs, but a JSON diff of moved boxes is far harder to read than a change to Mermaid source.

Common mistakes

• Trusting the browser to keep it: local storage is a cache, not a backup. Export anything that matters.
• Unbound arrows: an arrow that stops just short of a box won't follow it. Check that the box highlights before you let go.
• Posting a share link in a public channel: the key is in the link, so everyone who sees it can open the board.
• Exporting a PNG without the scene: if you need to change it later, you redraw it from scratch.
• Expecting every Mermaid diagram to become shapes: only supported types do, and the rest come in as a flat image.

Key takeaways

• Excalidraw is a free, open-source browser whiteboard for quick boxes-and-arrows diagrams, with no account and no install.
• One-key shortcuts (R for a box, A for an arrow) and arrows that bind to shapes make diagrams quick to draw and easy to rearrange.
• The hand-drawn look is deliberate: it keeps the discussion on the ideas, not the polish.
• Live sessions and shared links are end-to-end encrypted, with the key in the link itself, so treat the link like a password.
• Boards live in your browser, so export them as a PNG, an SVG or an .excalidraw file.