Angular whiteboard component
npm install ng-whiteboardLightweight 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
- šØ 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
Install via yarn:
``sh`
yarn add ng-whiteboard
or npm:
`sh`
npm install ng-whiteboard
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 {}
`
Import the component in your app.module.ts:
`typescript
import { NgWhiteboardComponent } from 'ng-whiteboard';
@NgModule({
imports: [NgWhiteboardComponent],
// other imports
})
export class AppModule {}
`
`html`
`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();
}
}
`
`html`
| 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 |
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();
}
}
`
- 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.
- elements: Signal
- elementsCount: Signal
- hasElements: Signal if the active board has any elements.
- 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
- 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.
- 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).
- setActiveTool(tool: ToolType) Sets the current drawing tool (e.g., pen, eraser, shape).
- 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.
- 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.
- 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.
- 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.
The whiteboard supports comprehensive keyboard shortcuts for enhanced productivity:
| 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 |
| Shortcut | Action |
| --------------------------------------- | ----------------------- |
| Ctrl/Cmd + Z | Undo last action |Ctrl/Cmd + Shift + Z
| / Ctrl/Cmd + Y | Redo last undone action |
| Shortcut | Action |
| ---------------------- | -------------- |
| Ctrl/Cmd + Shift + ] | Bring to front |Ctrl/Cmd + ]
| | Bring forward |Ctrl/Cmd + Shift + [
| | Send to back |Ctrl/Cmd + [
| | Send backward |
| 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 |
| 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) |
| 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.
Right-click on the canvas or elements to access the context menu with quick actions:
- Paste - Paste copied elements
- Select All - Select all elements on canvas
- Clear Canvas - Remove all elements
- 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.
The NgWhiteboardComponent emits the following events to notify about changes and interactions.
- ready Emitted when the whiteboard is fully initialized and ready for use.
- destroyed Emitted when the whiteboard is destroyed, allowing for cleanup.
- 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.
- 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.
- 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.
- imageAdded Emitted when an image is added to the whiteboard.
- selectedToolChange Triggered when the active drawing tool is changed.
- configChanged` Emitted when the whiteboard configuration settings are updated.
We welcome contributions! Feel free to submit issues, feature requests, or pull requests.
This project is licensed under the MIT License.