@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 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).

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',
  })}
/>
Copy

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