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
- 🏗 Future-proof and scalable design

📦 Installation

Install via yarn:

``sh
yarn add ng-whiteboard
`

or npm:

`sh
npm install ng-whiteboard
`

🔧 Integration

$3

Import the component directly in your standalone component:

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

@Component({
selector: 'my-component',
imports: [NgWhiteboardComponent],
template: '',
})
export class MyComponent {}
`

$3

Import the component in your app.module.ts:

`typescript
import { NgWhiteboardComponent } from 'ng-whiteboard';

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

🚀 Usage

$3

`html

`

$3

`typescript
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();
}
}
`

$3

`html

`

⚙️ 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

$3

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

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

@Component({
template: ,
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();
}
}
`

$3

$3

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

$3

- elements: Signal Returns elements from the active board.
- elementsCount: Signal Returns the number of elements on the active board.
- hasElements: Signal Returns true if the active board has any elements.

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

- 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:

$3

| Shortcut | Action |
| ---------------------- | --------------------------- |
| Ctrl/Cmd + A | Select all elements |
| Escape | Clear selection |
| Delete / Backspace | Delete selected elements |
| Ctrl/Cmd + C | Copy selected elements |
| Ctrl/Cmd + X | Cut selected elements |
| Ctrl/Cmd + V | Paste elements |
| Ctrl/Cmd + D | Duplicate selected elements |

$3

| Shortcut | Action |
| --------------------------------------- | ----------------------- |
| Ctrl/Cmd + Z | Undo last action |
| Ctrl/Cmd + Shift + Z / Ctrl/Cmd + Y | Redo last undone action |

$3

| Shortcut | Action |
| ---------------------- | -------------- |
| Ctrl/Cmd + Shift + ] | Bring to front |
| Ctrl/Cmd + ] | Bring forward |
| Ctrl/Cmd + Shift + [ | Send to back |
| Ctrl/Cmd + [ | Send backward |

$3

| Shortcut | Action |
| -------- | --------------- |
| V | Select tool |
| P | Pen tool |
| L | Line tool |
| R | Rectangle tool |
| E | Ellipse tool |
| A | Arrow tool |
| T | Text tool |
| I | Image tool |
| H | Hand tool (pan) |
| D | Eraser tool |

$3

| Shortcut | Action |
| ------------------------------- | --------------------------------------- |
| Ctrl/Cmd + + / Ctrl/Cmd + = | Zoom in |
| Ctrl/Cmd + - | Zoom out |
| Ctrl/Cmd + 0 | Reset zoom (100%) |
| Space + Drag | Pan canvas (when not in hand tool mode) |

$3

| Shortcut | Action |
| ------------------- | -------------------------------------- |
| Shift + Drag | Constrain proportions (drawing shapes) |
| Alt/Option + Drag | Draw from center (shapes) |
| Ctrl/Cmd + Drag | Duplicate while dragging |

> 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:

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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