@ludovicm67/simple-whiteboard

Simple Whiteboard

Home · Docs · Demo

Simple Whiteboard is a simple web-based whiteboard application that allows users to draw on a canvas.

The application is built as a Web Component using LitElement. This allows the whiteboard to be easily embedded in any web application regardless of the framework used.

Features

• Different drawing tools:
  • Rectangle
  • Circle
  • Line
  • Arrow
  • Pen
  • Text
  • Sticky note
  • Picture
• Move the canvas using the Move tool, the middle mouse button, or scrolling
• Reorder items in the stacking order (bring forward / send backward / to front / to back)
• Erase items by dragging the Eraser over them
• Clear the canvas
• Undo / redo (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z)
• Support mouse and touch input
• Optional dotted grid background
• Pan & pinch-to-zoom (zoom follows the cursor / pinch center)
• Export as a PNG image: the current view, the full board, or a selected area

Usage

Add the <simple-whiteboard> element to your page and drop the default tools in its tools slot:

<simple-whiteboard locale="en">
  <simple-whiteboard--tool-defaults slot="tools"></simple-whiteboard--tool-defaults>
</simple-whiteboard>

Attributes

Attribute	Type	Default	Description
locale	string	en	The UI language.
dotted-background	boolean	true	Render a dotted grid behind the content. Use ="false" to hide.
hide-locale-picker	boolean	false	Hide the language picker from the menu.
hide-tool-options	boolean	false	Hide the floating tool-options panel (useful for a compact/embedded board).
skip-clear-confirmation	boolean	false	Clear the board without asking for a confirmation first.
debug	boolean	false	Log debug information and show the pointer coordinates.

Undo / redo

Every drawing, edit, move, resize, deletion and clear can be undone and redone, either with the toolbar buttons, the keyboard (Ctrl/Cmd+Z to undo, Ctrl/Cmd+Shift+Z or Ctrl+Y to redo), or programmatically:

whiteboard.undo();
whiteboard.redo();
whiteboard.canUndo(); // boolean
whiteboard.canRedo(); // boolean

A history-changed event (detail: { canUndo, canRedo }) is emitted whenever availability changes, so a host application can keep its own controls in sync.

Theming

The look can be tweaked with CSS custom properties, for example:

simple-whiteboard {
  --sw-accent: #7c3aed;
}

Performance

The whiteboard is designed to stay light on the CPU:

• redraws are coalesced with requestAnimationFrame, so many updates in the same frame only trigger a single render;
• items that are outside the visible viewport are skipped (viewport culling);
• the dotted background only computes and draws the dots that are visible.

Development

npm install        # install the dependencies
npm run dev        # start the dev server
npm test           # run the unit tests (Node's built-in test runner)
npm run test:e2e   # run the Playwright end-to-end tests
npm run build      # type-check and build the library -> dist/
npm run build:site # build the marketing site      -> dist-site/

There are two layers of tests: fast unit tests for the pure lib/controller modules (npm test), and end-to-end tests under e2e/ that drive the real component in a browser — drawing, editing, undo/redo, export, the menu, i18n, cross-tab sync and the site pages (npm run test:e2e, which starts the dev server automatically). The first run needs the browser: npx playwright install chromium.

The dev server serves three pages:

Page	Description
/	Landing page (index.html)
/app.html	The interactive whiteboard demo
/api.html	API reference (attributes, methods, events, …)
/404.html	Not-found page (served by GitHub Pages)

Site assets live in public/ (favicons, robots.txt); sitemap.xml is generated at build time, taking each page's lastmod from its last git commit. None of them are copied into the published package.

There are two separate build outputs:

• npm run build produces dist/ — the library only (JS bundle, source map and TypeScript declarations). This is what gets published to npm (files: ["dist"]); it contains no HTML.
• npm run build:site produces dist-site/ — the three pages above, bundled for hosting (this is what the GitHub Pages workflow deploys).

Used Technologies

• LitElement - A simple base class for creating fast, lightweight web components.
• TypeScript - A typed superset of JavaScript that compiles to plain JavaScript.
• Rough.js - A small graphics library that lets you draw in a sketchy, hand-drawn-like, style.
• Perfect Freehand - A tiny library for rendering perfect freehand lines.
• Lucide Icons - Beautiful & consistent icons.

License

Simple Whiteboard is licensed under the MIT License.