Simple Whiteboard API

Installation

Install from npm:

npm install @ludovicm67/simple-whiteboard

Then import it once anywhere in your JavaScript. The import has the side effect of registering the <simple-whiteboard> custom element and its tools:

import "@ludovicm67/simple-whiteboard";

Quick start

Drop the element into your markup and add the tool-defaults element to its tools slot to register every built-in tool at once:

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

The element sizes itself to its container, so give it a width and a height (for example a full-height <main>).

Attributes

All attributes are optional and can also be set as properties.

Tools

Tools are individual custom elements placed in the tools slot. Use tool-defaults for the full set, or cherry-pick only the ones you need to keep the toolbar (and your bundle) lean:

<simple-whiteboard>
  <simple-whiteboard--tool-pointer slot="tools"></simple-whiteboard--tool-pointer>
  <simple-whiteboard--tool-pen slot="tools"></simple-whiteboard--tool-pen>
  <simple-whiteboard--tool-eraser slot="tools"></simple-whiteboard--tool-eraser>
</simple-whiteboard>

The built-in tool elements:

• simple-whiteboard--tool-pointer — select, move and resize items
• simple-whiteboard--tool-move — pan the canvas
• simple-whiteboard--tool-rect — rectangle
• simple-whiteboard--tool-circle — circle
• simple-whiteboard--tool-line — line
• simple-whiteboard--tool-arrow — arrow
• simple-whiteboard--tool-pen — freehand pen
• simple-whiteboard--tool-text — text
• simple-whiteboard--tool-sticky — sticky note
• simple-whiteboard--tool-picture — image
• simple-whiteboard--tool-eraser — object eraser
• simple-whiteboard--tool-clear — clear the canvas

Methods

Grab the element (document.querySelector("simple-whiteboard")) and call these directly.

History

Items

Stacking order

View & tools

Events

All events are CustomEvents dispatched on the element. Listen with board.addEventListener(name, handler).

items-updated types

The detail.type tells you what happened, so you can mirror the change to a store or a remote peer:

Theming

Every surface is driven by CSS custom properties. Override them on the element (or any ancestor) to restyle the whole UI:

simple-whiteboard {
  --sw-accent: #7c3aed;
  --sw-board: #fbfaff;
  --sw-radius: 14px;
}

Framework usage

Because it’s a standard custom element, it works in any framework. Import once at your entry point, then use the tag in your templates.

React

Use the tag directly (React 19+ handles custom elements natively). Set boolean attributes as you would any DOM attribute, and attach a ref to call methods or listen to events.

import "@ludovicm67/simple-whiteboard";
import { useEffect, useRef } from "react";

export function Board() {
  const ref = useRef(null);
  useEffect(() => {
    const el = ref.current;
    const onChange = (e) => console.log(e.detail);
    el.addEventListener("items-updated", onChange);
    return () => el.removeEventListener("items-updated", onChange);
  }, []);

  return (
    <simple-whiteboard ref={ref} locale="en">
      <simple-whiteboard--tool-defaults slot="tools" />
    </simple-whiteboard>
  );
}

Collaboration

The whiteboard doesn’t ship a transport — instead, every change emits an items-updated event, and every method takes an optional sendEvent flag so you can apply a remote change without echoing it back. That’s all you need to build real-time sync over any channel (WebSocket, WebRTC, or, as in the demo, a BroadcastChannel between tabs):

const channel = new BroadcastChannel("whiteboard");

// Broadcast local changes to peers.
board.addEventListener("items-updated", (e) => {
  if (e.detail.type === "add") {
    channel.postMessage({ type: "add", item: e.detail.item });
  }
});

// Apply remote changes without re-broadcasting (sendEvent = false).
channel.onmessage = (e) => {
  if (e.data.type === "add") board.importItem(e.data.item);
};

See it working: open the live demo in two browser tabs and draw — the boards stay in sync.