ng-whiteboard

Lightweight angular 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, and Save functionalities
• 🖊️ Multiple drawing tools (pen, shapes, text, etc.)
• 🏗 Future-proof and scalable design

📦 Installation

Install via yarn:

yarn add ng-whiteboard

or npm:

npm install ng-whiteboard

Import the module in your app.module.ts:

import { NgWhiteboardModule } from 'ng-whiteboard';

@NgModule({
  imports: [BrowserModule, NgWhiteboardModule],
  bootstrap: [AppComponent],
})
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

Input	Type	Default	Description
[data]	WhiteboardElement[]	[]	The whiteboard data
[options]	WhiteboardOptions	null	Component configuration object, properties described below
[drawingEnabled]	boolean	true	Enable mouse/touch interactions
[selectedTool]	ToolType	ToolType.Pen	The current selected tool
[canvasWidth]	number	800	The width of whiteboard canvas
[canvasHeight]	number	600	The height of whiteboard canvas
[fullScreen]	boolean	true	If true, change (canvasWidth, canvasHeight) to fit the parent container
[strokeColor]	string	#333333	The default stroke color
[backgroundColor]	string	#F8F9FA	The default background color
[fill]	string	transparent	The default fill color
[strokeWidth]	number	2	The default stroke width
[zoom]	number	1	Zoom level
[fontFamily]	string	sans-serif	The default font family
[fontSize]	number	24	The default font size
[center]	boolean	true	Center the canvas in parent component, works with fullScreen: false
[x]	number	0	If center is false, set the X axis
[y]	number	0	If center is false, set the Y axis
[enableGrid]	boolean	false	Enable the grid pattern
[gridSize]	number	10	Set the grid inner boxes size
[snapToGrid]	boolean	false	Enable snapping to grid
[lineJoin]	LineJoin	LineJoin.Miter	The default Line join
[lineCap]	LineCap	LineCap.Butt	The default Line cap
[dasharray]	string	''	The default dash-array
[dashoffset]	number	0	The default dash-offset

📖 API Reference

WhiteboardService Methods

📌 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.
• removeElement(id: string)
  Removes an element from the whiteboard by its ID.
• updateElement(element: WhiteboardElement)
  Updates an existing element with new properties.
• updateSelectedElement(partialElement: Partial<WhiteboardElement>)
  Modifies only specific properties of the currently selected element.
• selectElement(element: WhiteboardElement | null)
  Selects or deselects an element 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.

📢 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

• elementAdded
  Emitted when a new element is added to the whiteboard.
• elementUpdated
  Triggered when an existing element is modified.
• elementSelected
  Emitted when an element is selected.
• elementDeleted
  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.