ng-whiteboard

ng-whiteboard is a feature-rich, modular, and flexible whiteboard library for Angular. Designed for ease of use, performance, and a seamless drawing experience. It provides essential drawing tools and features with a scalable architecture.

🔗 Live Demo

✨ Features

• 🎨 SVG-based rendering for high-quality visuals
• ⚡ Optimized performance for smooth interactions
• 📦 Modular, tree-shakable, and lightweight architecture
• 🛠️ Comprehensive Public API via WhiteboardService and component bindings
• 📏 Undo/Redo, Zoom, Pan, and Save functionalities
• 🖊️ Multiple drawing tools (pen, shapes, text, eraser, hand tool, etc.)
• 🔄 Multi-instance support - Run multiple independent whiteboards simultaneously
• ⌨️ Keyboard shortcuts - Full keyboard support for common operations
• 📋 Context menu - Right-click menu for quick actions
• 📑 Layer management - Control element z-index and stacking order
• ✂️ Copy/Paste/Cut - Full clipboard support for elements
• 🎯 Selection tools - Select, move, resize, and rotate elements
• 🔗 Arrows - Arrows with customizable heads, and smart element binding
• 🏗 Future-proof and scalable design

📦 Installation

Install via yarn:

yarn add ng-whiteboard

or npm:

npm install ng-whiteboard

🔧 Integration

For Standalone Components

Import the component directly in your standalone component:

import { Component } from '@angular/core';
import { NgWhiteboardComponent } from 'ng-whiteboard';

@Component({
  selector: 'my-component',
  imports: [NgWhiteboardComponent],
  template: '<ng-whiteboard></ng-whiteboard>',
})
export class MyComponent {}

For NgModules

Import the component in your app.module.ts:

import { NgWhiteboardComponent } from 'ng-whiteboard';

@NgModule({
  imports: [NgWhiteboardComponent],
  // other imports
})
export class AppModule {}

🚀 Usage

Basic Example

<ng-whiteboard></ng-whiteboard>

Advanced Example With Persist Data

import { Component, OnInit } from '@angular/core';
import { WhiteboardService } from 'ng-whiteboard';

@Component({
  selector: 'app-whiteboard-container',
  templateUrl: './whiteboard-container.component.html',
  styleUrls: ['./whiteboard-container.component.css'],
})
export class WhiteboardContainerComponent implements OnInit {
  whiteboardOptions: WhiteboardOptions = {
    backgroundColor: '#fff',
    strokeColor: '#2c80b1',
    strokeWidth: 5,
  };

  constructor(private whiteboardService: WhiteboardService) {}

  ngOnInit() {
    const savedData = localStorage.getItem('whiteboardData');
    if (savedData) {
      this.data = JSON.parse(savedData);
    }
  }

  onDataChange(data: WhiteboardElement[]) {
    localStorage.setItem('whiteboardData', JSON.stringify(data));
  }

  clearBoard() {
    this.whiteboardService.clear();
  }
}

Component Integration

<ng-whiteboard (dataChange)="onDataChange($event)" [options]="whiteboardOptions"></ng-whiteboard>

⚙️ Configuration

🏹 Arrow Configuration

The arrowConfig property controls the default appearance of newly drawn arrows.

import { ArrowConfig } from 'ng-whiteboard';

const config: Partial<WhiteboardConfig> = {
  arrowConfig: {
    startHeadStyle: 'none',
    endHeadStyle: 'open-arrow',
    lineStyle: 'curve',
  },
};

<ng-whiteboard [config]="config"></ng-whiteboard>

ArrowConfig Properties

ArrowHeadStyle Values

ArrowLineStyle Values

Arrow Drawing Modifiers

Smart Element Binding

Arrows can automatically bind to other elements (rectangles, ellipses, images, and text). When an arrow endpoint is dragged near a connectable element, it snaps to the nearest connection point and creates a binding. Bound arrows automatically update their position when the connected element is moved or resized.

Connection Points per Shape:

📖 API Reference

Important: Multi-Instance Support

ng-whiteboard supports multiple independent whiteboard instances. When using WhiteboardService, you must specify which board you're working with:

import { Component, AfterViewInit, inject } from '@angular/core';
import { NgWhiteboardService } from 'ng-whiteboard';

@Component({
  template: ` <ng-whiteboard [boardId]="boardId"></ng-whiteboard> `,
  providers: [NgWhiteboardService],
})
export class MyWhiteboardComponent implements AfterViewInit {
  private whiteboardService = inject(NgWhiteboardService);
  boardId = 'my-unique-board-id';

  ngAfterViewInit() {
    // IMPORTANT: Set the active board before using service methods
    this.whiteboardService.setActiveBoard(this.boardId);
  }

  clearBoard() {
    // Now this works on the correct board
    this.whiteboardService.clear();
  }
}

WhiteboardService Methods

🔀 Multi-Instance Management

• setActiveBoard(boardId: string) Sets the specified board as active. All service operations will target this board.
• activeBoard() Returns the ID of the currently active board, or null if no board is active.
• clearActiveBoard() Clears the active board.
• getAllBoards() Returns an array of all registered board IDs.
• getBoardCount() Returns the total number of registered boards.
• hasBoard(boardId: string) Checks if a board with the specified ID exists.

📊 Reactive Signals (Active Board)

• elements: Signal<WhiteboardElement[]> Returns elements from the active board.
• elementsCount: Signal<number> Returns the number of elements on the active board.
• hasElements: Signal<boolean> Returns true if the active board has any elements.

📌 Element Management

• addElement(element: WhiteboardElement) Adds a new element (e.g., shape, text) to the whiteboard.
• addImage(image: string, x?: number, y?: number) Adds an image to the whiteboard at a specified position.
• removeElements(ids: string[]) Removes elements from the whiteboard by IDs.
• updateElement(element: WhiteboardElement) Updates an existing element with new properties.
• updateSelectedElements(partialElement: Partial<WhiteboardElement>) Modifies only specific properties of the currently selected element.
• selectElements(elementsOrIds: WhiteboardElement | WhiteboardElement[] | string | string[]) Select element(s) on the whiteboard.
• deselectElement(elementOrId: WhiteboardElement | string) Deselects a specific element on the whiteboard.
• toggleSelection(elementOrId: WhiteboardElement | string) Toggle the selection of an element on the whiteboard.
• selectAll() Selects all elements currently present on the whiteboard.
• clearSelection() Clears any currently selected elements on the whiteboard.

🔄 State Management

• clear() Clears all elements from the whiteboard.
• undo() Reverts the last action.
• redo() Restores the last undone action.
• save(format = FormatType.Base64, name = 'New board') Saves the current whiteboard state in the specified format (e.g., Base64, JSON, SVG).

🖌 Drawing Tools & Interaction

• setActiveTool(tool: ToolType) Sets the current drawing tool (e.g., pen, eraser, shape).

🎨 Canvas Control

• setCanvasDimensions(width: number, height: number) Sets the width and height of the whiteboard canvas.
• setCanvasPosition(x: number, y: number) Moves the canvas to a specific position.
• centerCanvas() Centers the whiteboard canvas within the viewport.
• fullScreen() Toggles full-screen mode for the whiteboard.
• toggleGrid() Enables or disables the background grid for alignment.
• dispatchBatch(actions: WhiteboardAction[]) Dispatches a batch of actions to the whiteboard.

📑 Layer Management

• bringToFront(elementOrId: WhiteboardElement | string) Brings the specified element to the front (highest z-index).
• bringForward(elementOrId: WhiteboardElement | string) Moves the element one layer forward.
• sendToBack(elementOrId: WhiteboardElement | string) Sends the specified element to the back (lowest z-index).
• sendBackward(elementOrId: WhiteboardElement | string) Moves the element one layer backward.
• setZIndex(elementOrId: WhiteboardElement | string, zIndex: number) Sets the exact z-index for an element.
• getZIndex(elementOrId: WhiteboardElement | string) Returns the current z-index of an element.

✂️ Clipboard Operations

• copy() Copies the currently selected elements to the clipboard.
• cut() Cuts the currently selected elements (copies and removes them).
• paste() Pastes elements from the clipboard at the current cursor position.
• duplicate() Duplicates the currently selected elements.

🔍 Viewport Control

• zoomIn() Increases the zoom level.
• zoomOut() Decreases the zoom level.
• setZoom(level: number) Sets the zoom level to a specific value.
• resetZoom() Resets the zoom level to 100%.
• pan(deltaX: number, deltaY: number) Pans the canvas by the specified offset.
• resetPan() Resets the canvas to its original position.

⌨️ Keyboard Shortcuts

The whiteboard supports comprehensive keyboard shortcuts for enhanced productivity:

Selection & Editing

Undo/Redo

Layer Management

Tools

Viewport

Modifiers

Note: Ctrl is used on Windows/Linux, Cmd (⌘) is used on macOS.

📋 Context Menu

Right-click on the canvas or elements to access the context menu with quick actions:

Canvas Context Menu

• Paste - Paste copied elements
• Select All - Select all elements on canvas
• Clear Canvas - Remove all elements

Element Context Menu

• Cut - Cut selected element(s)
• Copy - Copy selected element(s)
• Paste - Paste from clipboard
• Duplicate - Create a copy of selected element(s)
• Delete - Remove selected element(s)
• Bring to Front - Move to top layer
• Bring Forward - Move one layer up
• Send to Back - Move to bottom layer
• Send Backward - Move one layer down

The context menu is context-aware and shows relevant options based on the current selection and clipboard state.

📢 Whiteboard Events (Outputs)

The NgWhiteboardComponent emits the following events to notify about changes and interactions.

🟢 Lifecycle Events

• ready Emitted when the whiteboard is fully initialized and ready for use.
• destroyed Emitted when the whiteboard is destroyed, allowing for cleanup.

✏️ Drawing Events

• drawStart Triggered when a user starts drawing on the whiteboard.
• drawing Emitted continuously while the user is drawing.
• drawEnd Triggered when the user stops drawing.

🔄 State & Data Events

• undo Emitted when an undo action is performed.
• redo Emitted when a redo action is performed.
• clear Triggered when the whiteboard is cleared.
• dataChange Emitted when the whiteboard's internal data state changes.
• save Triggered when the whiteboard state is saved.

📌 Element Events

• elementsAdded Emitted when a new element is added to the whiteboard.
• elementsUpdated Triggered when an existing element is modified.
• elementsSelected Emitted when an element is selected.
• elementsDeleted Triggered when an element is removed.

🖼 Image Events

• imageAdded Emitted when an image is added to the whiteboard.

🛠 Configuration & Tool Events

• selectedToolChange Triggered when the active drawing tool is changed.
• configChanged Emitted when the whiteboard configuration settings are updated.

🤝 Contributing

We welcome contributions! Feel free to submit issues, feature requests, or pull requests.

📜 License

This project is licensed under the MIT License.