@hiyve/react-whiteboard

Real-time collaborative whiteboard component with full multi-user synchronization.

Installation

npx @hiyve/cli login
npm install @hiyve/react-whiteboard
Copy

Quick Start

import { Whiteboard, WhiteboardToolbar, ZoomToolbar } from '@hiyve/react-whiteboard';
import { HiyveProvider } from '@hiyve/react';

function App() {
  return (
    <HiyveProvider region="us-east-2" generateRoomToken={generateToken}>
      <WhiteboardRoom />
    </HiyveProvider>
  );
}

function WhiteboardRoom() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
      <WhiteboardToolbar />
      <div style={{ flex: 1, position: 'relative' }}>
        <Whiteboard />
        <ZoomToolbar />
      </div>
    </div>
  );
}
Copy

Components

Hooks

Dialogs

Add-in System

Extend the whiteboard with custom tools using the add-in API. Add-ins can contribute toolbar buttons, context menu items, and custom object types.

Using Built-in Add-ins

import { Whiteboard } from '@hiyve/react-whiteboard';

<Whiteboard
  fileId={fileId}
  enableAddins
  enabledAddins={['sticky-notes']}
/>
Copy

Creating a Custom Add-in

import { WhiteboardAddin } from '@hiyve/react-whiteboard';
import type { ToolbarButton, ContextMenuItem, WhiteboardObject } from '@hiyve/react-whiteboard';

class StampAddin extends WhiteboardAddin {
  constructor() {
    super({
      id: 'stamps',
      name: 'Stamps',
      description: 'Add stamp annotations to the whiteboard',
    });
  }

  getToolbarButtons(): ToolbarButton[] {
    return [{
      id: 'add-stamp',
      label: 'Add Stamp',
      icon: <StampIcon />,
      action: () => this.placeStamp(),
    }];
  }

  getContextMenuItems(object: WhiteboardObject): ContextMenuItem[] {
    if (!this.isAddinObject(object)) return [];
    return [{ id: 'remove-stamp', label: 'Remove Stamp', action: () => { /* ... */ } }];
  }

  getObjectTypes(): string[] {
    return ['stamp'];
  }

  onMessage(message: unknown, fromUserId: string): void {
    // Handle messages from other users
  }

  exportData(): unknown {
    // Return data to persist
    return {};
  }

  private placeStamp(): void {
    // Create and add stamp to canvas
  }
}
Copy

Using the Registry Directly

import { WhiteboardAddinRegistry, StickyNotesAddin } from '@hiyve/react-whiteboard';

const registry = new WhiteboardAddinRegistry();
registry.register(new StickyNotesAddin());
registry.register(new StampAddin());

// Enable specific add-ins
registry.enable('sticky-notes');
registry.enable('stamps');

// Get toolbar buttons from all enabled add-ins
const buttons = registry.getToolbarButtons();

// Listen for lifecycle events
registry.addEventListener('addin-enabled', ({ addinId }) => {
  console.log(`${addinId} was enabled`);
});
Copy

Props

Whiteboard

WhiteboardToolbar

ZoomToolbar

SelectionShortcutMenu accepts SelectionShortcutMenuProps for wiring up actions on the currently selected object(s).

Background rasters

Background pages (images and rendered PDF pages) are embedded in the whiteboard file as data URLs. They are capped to 2500 px on the long side and 5000 px tall and encoded as WebP (JPEG where the browser cannot encode WebP). Each page also carries a small thumbDataUrl used by the page drawer. Files saved by earlier versions with large PNG pages load unchanged and are re-encoded in the background; the smaller raster is persisted on the next save.

Features

• Real-time collaboration across all connected users
• Drawing tools: pencil, shapes (rectangle, circle, triangle), text
• Shape fill modes: filled or outlined
• Zoom and pan with mouse wheel and touch gestures
• Undo/redo with full history
• Laser pointer for presentations (multiple colors per user)
• File persistence with auto-save
• Owner presence detection (read-only when owner leaves)
• Extensible add-in system for custom tools and objects
• Keyboard shortcuts for common operations

Keyboard Shortcuts

Utility Functions

Coordinate, serialization, and file utilities are exported for advanced use cases.

Coordinate Utilities

import {
  viewportToCanvas,
  canvasToViewport,
  getViewportCenter,
  calculateBoundingBox,
  distance,
  interpolatePosition,
} from '@hiyve/react-whiteboard';
Copy

Canvas Object Helpers

import {
  findObjectById,
  removeObjectById,
  serializeObject,
  serializeCanvas,
  recreateObject,
  createShape,
  loadCanvasFromJSON,
  clearCanvas,
  getSyncableObjects,
} from '@hiyve/react-whiteboard';
Copy

Object ID Utilities

import {
  createObjectIdGenerator,
  parseObjectId,
  isObjectOwnedBy,
  generateAddinObjectId,
} from '@hiyve/react-whiteboard';
Copy

File Creation

import { createWhiteboardFile, createAndShareWhiteboardFile } from '@hiyve/react-whiteboard';
import type { CreateWhiteboardFileOptions, WhiteboardFileClient } from '@hiyve/react-whiteboard';
Copy

Thumbnail Generation

Render a saved whiteboard file to a small preview image. whiteboardThumbnailGenerator plugs directly into a file manager's thumbnailGenerators prop so card views show the actual drawing:

import { whiteboardThumbnailGenerator } from '@hiyve/react-whiteboard';

<FileManager
  enableClientThumbnails
  thumbnailGenerators={[whiteboardThumbnailGenerator]}
/>
Copy

Additional Utilities

Constants

Pre-defined configuration values are available for reference or customization.

Customization

Colors

import { Whiteboard, mergeWhiteboardColors } from '@hiyve/react-whiteboard';

<Whiteboard
  colors={mergeWhiteboardColors({
    canvasBackground: '#f5f5f5',
    gridColor: '#e0e0e0',
    toolbarBackground: '#1e1e1e',
    activeToolHighlight: '#ff9800',
    defaultDrawColor: '#333333',
  })}
/>
Copy

Labels

import { Whiteboard, mergeWhiteboardLabels } from '@hiyve/react-whiteboard';

<Whiteboard
  labels={mergeWhiteboardLabels({
    pencilTool: 'Draw',
    clearCanvas: 'Erase All',
    readOnlyMode: 'Viewing Mode',
    loadingBackground: 'Rendering page…',
  })}
/>
Copy

loadingBackground is shown over the canvas while a background page is being rendered (on open, on page turn, during a PDF import or a peer rebuild); loading covers the file content itself.

Styles

import { Whiteboard, mergeWhiteboardStyles } from '@hiyve/react-whiteboard';

<Whiteboard
  styles={mergeWhiteboardStyles({
    defaultStrokeWidth: 3,
    toolbarHeight: 64,
    buttonBorderRadius: 8,
    autoSaveInterval: 10000,
  })}
/>
Copy

Icons

import { Whiteboard, mergeWhiteboardIcons } from '@hiyve/react-whiteboard';
import BrushIcon from '@mui/icons-material/Brush';

<Whiteboard
  icons={mergeWhiteboardIcons({
    pencil: <BrushIcon />,
  })}
/>
Copy

Requirements

• React 18+
• @hiyve/react with HiyveProvider
• @mui/material v5 or v6
• @mui/icons-material v5 or v6
• Canvas rendering library is bundled -- no separate installation needed
• @hiyve/react-collaboration (optional, for hosting Whiteboard inside FileSessionHost and file sharing dialogs)

License

Proprietary - Hiyve SDK