\n\n**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.\n\nš **[Live Demo](https://mostafazke.github.io/ng-whiteboard)**\n\n## āØ Features\n\n- šØ **SVG-based rendering** for high-quality visuals\n- ā” **Optimized performance** for smooth interactions\n- š¦ **Modular, tree-shakable, and lightweight architecture**\n- š ļø **Comprehensive Public API** via `WhiteboardService` and component bindings\n- š **Undo/Redo, Zoom, Pan, and Save functionalities**\n- šļø **Multiple drawing tools** (pen, shapes, text, eraser, hand tool, etc.)\n- š **Multi-instance support** - Run multiple independent whiteboards simultaneously\n- āØļø **Keyboard shortcuts** - Full keyboard support for common operations\n- š **Context menu** - Right-click menu for quick actions\n- š **Layer management** - Control element z-index and stacking order\n- āļø **Copy/Paste/Cut** - Full clipboard support for elements\n- šÆ **Selection tools** - Select, move, resize, and rotate elements\n- š **Arrows** - Arrows with customizable heads, and smart element binding\n- š **Future-proof and scalable design**\n\n## š¦ Installation\n\nInstall via yarn:\n\n```sh\nyarn add ng-whiteboard\n```\n\nor npm:\n\n```sh\nnpm install ng-whiteboard\n```\n\n## š§ Integration\n\n### For Standalone Components\n\nImport the component directly in your standalone component:\n\n```typescript\nimport { Component } from '@angular/core';\nimport { NgWhiteboardComponent } from 'ng-whiteboard';\n\n@Component({\n selector: 'my-component',\n imports: [NgWhiteboardComponent],\n template: '',\n})\nexport class MyComponent {}\n```\n\n### For NgModules\n\nImport the component in your `app.module.ts`:\n\n```typescript\nimport { NgWhiteboardComponent } from 'ng-whiteboard';\n\n@NgModule({\n imports: [NgWhiteboardComponent],\n // other imports\n})\nexport class AppModule {}\n```\n\n## š Usage\n\n### Basic Example\n\n```html\n\n```\n\n### Advanced Example With Persist Data\n\n```typescript\nimport { Component, OnInit } from '@angular/core';\nimport { WhiteboardService } from 'ng-whiteboard';\n\n@Component({\n selector: 'app-whiteboard-container',\n templateUrl: './whiteboard-container.component.html',\n styleUrls: ['./whiteboard-container.component.css'],\n})\nexport class WhiteboardContainerComponent implements OnInit {\n whiteboardOptions: WhiteboardOptions = {\n backgroundColor: '#fff',\n strokeColor: '#2c80b1',\n strokeWidth: 5,\n };\n\n constructor(private whiteboardService: WhiteboardService) {}\n\n ngOnInit() {\n const savedData = localStorage.getItem('whiteboardData');\n if (savedData) {\n this.data = JSON.parse(savedData);\n }\n }\n\n onDataChange(data: WhiteboardElement[]) {\n localStorage.setItem('whiteboardData', JSON.stringify(data));\n }\n\n clearBoard() {\n this.whiteboardService.clear();\n }\n}\n```\n\n### Component Integration\n\n```html\n\n```\n\n## āļø Configuration\n\n| Input | Type | Default | Description |\n| ------------------- | --------------------- | ---------------- | -------------------------------------------------------------------------------------------------- |\n| `[data]` | `WhiteboardElement[]` | `[]` | The whiteboard data |\n| `[options]` | `WhiteboardOptions` | `null` | Component configuration object, properties described below |\n| `[drawingEnabled]` | `boolean` | `true` | Enable mouse/touch interactions |\n| `[selectedTool]` | `ToolType` | `ToolType.Pen` | The current selected tool |\n| `[canvasWidth]` | `number` | `800` | The width of whiteboard canvas |\n| `[canvasHeight]` | `number` | `600` | The height of whiteboard canvas |\n| `[fullScreen]` | `boolean` | `true` | If true, change (canvasWidth, canvasHeight) to fit the parent container |\n| `[strokeColor]` | `string` | `#333333` | The default stroke color |\n| `[backgroundColor]` | `string` | `#F8F9FA` | The default background color |\n| `[fill]` | `string` | `transparent` | The default fill color |\n| `[strokeWidth]` | `number` | `2` | The default stroke width |\n| `[zoom]` | `number` | `1` | Zoom level |\n| `[fontFamily]` | `string` | `sans-serif` | The default font family |\n| `[fontSize]` | `number` | `24` | The default font size |\n| `[center]` | `boolean` | `true` | Center the canvas in parent component, works with `fullScreen: false` |\n| `[x]` | `number` | `0` | If `center` is false, set the X axis |\n| `[y]` | `number` | `0` | If `center` is false, set the Y axis |\n| `[enableGrid]` | `boolean` | `false` | Enable the grid pattern |\n| `[gridSize]` | `number` | `10` | Set the grid inner boxes size |\n| `[snapToGrid]` | `boolean` | `false` | Enable snapping to grid |\n| `[lineJoin]` | `LineJoin` | `LineJoin.Miter` | The default Line join |\n| `[lineCap]` | `LineCap` | `LineCap.Butt` | The default Line cap |\n| `[dasharray]` | `string` | `''` | The default dash-array |\n| `[dashoffset]` | `number` | `0` | The default dash-offset |\n| `[arrowConfig]` | `ArrowConfig` | See below | Arrow-specific configuration (heads, line style). See [Arrow Configuration](#-arrow-configuration) |\n\n## š¹ Arrow Configuration\n\nThe `arrowConfig` property controls the default appearance of newly drawn arrows.\n\n```typescript\nimport { ArrowConfig } from 'ng-whiteboard';\n\nconst config: Partial = {\n arrowConfig: {\n startHeadStyle: 'none',\n endHeadStyle: 'open-arrow',\n lineStyle: 'curve',\n },\n};\n```\n\n```html\n\n```\n\n### `ArrowConfig` Properties\n\n| Property | Type | Default | Description |\n| ---------------- | ---------------- | -------------- | ----------------------------------------- |\n| `startHeadStyle` | `ArrowHeadStyle` | `'none'` | Arrowhead style at the start of the arrow |\n| `endHeadStyle` | `ArrowHeadStyle` | `'open-arrow'` | Arrowhead style at the end of the arrow |\n| `lineStyle` | `ArrowLineStyle` | `'curve'` | Default path type for new arrows |\n\n### `ArrowHeadStyle` Values\n\n| Value | Description |\n| ---------------- | --------------------------------- |\n| `'none'` | No arrowhead |\n| `'arrow'` | Filled triangle |\n| `'open-arrow'` | Open V-chevron (stroked) |\n| `'diamond'` | Filled diamond |\n| `'open-diamond'` | Open diamond outline |\n| `'circle'` | Filled circle |\n| `'open-circle'` | Open circle outline |\n| `'bar'` | Vertical bar (perpendicular line) |\n\n### `ArrowLineStyle` Values\n\n| Value | Description |\n| ------------ | -------------------------------------------------------------------- |\n| `'straight'` | Direct line between start and end points |\n| `'curve'` | Smooth quadratic curve with a draggable control point |\n| `'elbow'` | Right-angle (orthogonal) connector with a configurable bend position |\n\n### Arrow Drawing Modifiers\n\n| Modifier | Behavior |\n| ----------------- | -------------------------------------------------- |\n| `Shift + Drag` | Constrains arrow angle to 15Ā° increments |\n| Drag near element | Auto-snaps to connection points (20px snap radius) |\n\n### Smart Element Binding\n\nArrows 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.\n\n**Connection Points per Shape:**\n\n| Shape | Connection Points |\n| --------- | --------------------------------------------------------------- |\n| Rectangle | 8 points ā top, right, bottom, left, and 4 corners |\n| Ellipse | 8 points ā cardinal directions and 45Ā° positions on the ellipse |\n| Image | 4 cardinal points (top, right, bottom, left) |\n| Text | 4 cardinal points (top, right, bottom, left) |\n\n## š API Reference\n\n### Important: Multi-Instance Support\n\n**ng-whiteboard** supports multiple independent whiteboard instances. When using `WhiteboardService`, you must specify which board you're working with:\n\n```typescript\nimport { Component, AfterViewInit, inject } from '@angular/core';\nimport { NgWhiteboardService } from 'ng-whiteboard';\n\n@Component({\n template: ` `,\n providers: [NgWhiteboardService],\n})\nexport class MyWhiteboardComponent implements AfterViewInit {\n private whiteboardService = inject(NgWhiteboardService);\n boardId = 'my-unique-board-id';\n\n ngAfterViewInit() {\n // IMPORTANT: Set the active board before using service methods\n this.whiteboardService.setActiveBoard(this.boardId);\n }\n\n clearBoard() {\n // Now this works on the correct board\n this.whiteboardService.clear();\n }\n}\n```\n\n### `WhiteboardService` Methods\n\n### š Multi-Instance Management\n\n- **`setActiveBoard(boardId: string)`** Sets the specified board as active. All service operations will target this board.\n- **`activeBoard()`** Returns the ID of the currently active board, or `null` if no board is active.\n- **`clearActiveBoard()`** Clears the active board.\n- **`getAllBoards()`** Returns an array of all registered board IDs.\n- **`getBoardCount()`** Returns the total number of registered boards.\n- **`hasBoard(boardId: string)`** Checks if a board with the specified ID exists.\n\n### š Reactive Signals (Active Board)\n\n- **`elements: Signal`** Returns elements from the active board.\n- **`elementsCount: Signal`** Returns the number of elements on the active board.\n- **`hasElements: Signal`** Returns `true` if the active board has any elements.\n\n### š Element Management\n\n- **`addElement(element: WhiteboardElement)`** Adds a new element (e.g., shape, text) to the whiteboard.\n- **`addImage(image: string, x?: number, y?: number)`** Adds an image to the whiteboard at a specified position.\n- **`removeElements(ids: string[])`** Removes elements from the whiteboard by IDs.\n- **`updateElement(element: WhiteboardElement)`** Updates an existing element with new properties.\n- **`updateSelectedElements(partialElement: Partial)`** Modifies only specific properties of the currently selected element.\n- **`selectElements(elementsOrIds: WhiteboardElement | WhiteboardElement[] | string | string[])`** Select element(s) on the whiteboard.\n- **`deselectElement(elementOrId: WhiteboardElement | string)`** Deselects a specific element on the whiteboard.\n- **`toggleSelection(elementOrId: WhiteboardElement | string)`** Toggle the selection of an element on the whiteboard.\n- **`selectAll()`** Selects all elements currently present on the whiteboard.\n- **`clearSelection()`** Clears any currently selected elements on the whiteboard.\n\n### š State Management\n\n- **`clear()`** Clears all elements from the whiteboard.\n- **`undo()`** Reverts the last action.\n- **`redo()`** Restores the last undone action.\n- **`save(format = FormatType.Base64, name = 'New board')`** Saves the current whiteboard state in the specified format (e.g., Base64, JSON, SVG).\n\n### š Drawing Tools & Interaction\n\n- **`setActiveTool(tool: ToolType)`** Sets the current drawing tool (e.g., pen, eraser, shape).\n\n### šØ Canvas Control\n\n- **`setCanvasDimensions(width: number, height: number)`** Sets the width and height of the whiteboard canvas.\n- **`setCanvasPosition(x: number, y: number)`** Moves the canvas to a specific position.\n- **`centerCanvas()`** Centers the whiteboard canvas within the viewport.\n- **`fullScreen()`** Toggles full-screen mode for the whiteboard.\n- **`toggleGrid()`** Enables or disables the background grid for alignment.\n- **`dispatchBatch(actions: WhiteboardAction[])`** Dispatches a batch of actions to the whiteboard.\n\n### š Layer Management\n\n- **`bringToFront(elementOrId: WhiteboardElement | string)`** Brings the specified element to the front (highest z-index).\n- **`bringForward(elementOrId: WhiteboardElement | string)`** Moves the element one layer forward.\n- **`sendToBack(elementOrId: WhiteboardElement | string)`** Sends the specified element to the back (lowest z-index).\n- **`sendBackward(elementOrId: WhiteboardElement | string)`** Moves the element one layer backward.\n- **`setZIndex(elementOrId: WhiteboardElement | string, zIndex: number)`** Sets the exact z-index for an element.\n- **`getZIndex(elementOrId: WhiteboardElement | string)`** Returns the current z-index of an element.\n\n### āļø Clipboard Operations\n\n- **`copy()`** Copies the currently selected elements to the clipboard.\n- **`cut()`** Cuts the currently selected elements (copies and removes them).\n- **`paste()`** Pastes elements from the clipboard at the current cursor position.\n- **`duplicate()`** Duplicates the currently selected elements.\n\n### š Viewport Control\n\n- **`zoomIn()`** Increases the zoom level.\n- **`zoomOut()`** Decreases the zoom level.\n- **`setZoom(level: number)`** Sets the zoom level to a specific value.\n- **`resetZoom()`** Resets the zoom level to 100%.\n- **`pan(deltaX: number, deltaY: number)`** Pans the canvas by the specified offset.\n- **`resetPan()`** Resets the canvas to its original position.\n\n## āØļø Keyboard Shortcuts\n\nThe whiteboard supports comprehensive keyboard shortcuts for enhanced productivity:\n\n### Selection & Editing\n\n| Shortcut | Action |\n| ---------------------- | --------------------------- |\n| `Ctrl/Cmd + A` | Select all elements |\n| `Escape` | Clear selection |\n| `Delete` / `Backspace` | Delete selected elements |\n| `Ctrl/Cmd + C` | Copy selected elements |\n| `Ctrl/Cmd + X` | Cut selected elements |\n| `Ctrl/Cmd + V` | Paste elements |\n| `Ctrl/Cmd + D` | Duplicate selected elements |\n\n### Undo/Redo\n\n| Shortcut | Action |\n| --------------------------------------- | ----------------------- |\n| `Ctrl/Cmd + Z` | Undo last action |\n| `Ctrl/Cmd + Shift + Z` / `Ctrl/Cmd + Y` | Redo last undone action |\n\n### Layer Management\n\n| Shortcut | Action |\n| ---------------------- | -------------- |\n| `Ctrl/Cmd + Shift + ]` | Bring to front |\n| `Ctrl/Cmd + ]` | Bring forward |\n| `Ctrl/Cmd + Shift + [` | Send to back |\n| `Ctrl/Cmd + [` | Send backward |\n\n### Tools\n\n| Shortcut | Action |\n| -------- | --------------- |\n| `V` | Select tool |\n| `P` | Pen tool |\n| `L` | Line tool |\n| `R` | Rectangle tool |\n| `E` | Ellipse tool |\n| `A` | Arrow tool |\n| `T` | Text tool |\n| `I` | Image tool |\n| `H` | Hand tool (pan) |\n| `D` | Eraser tool |\n\n### Viewport\n\n| Shortcut | Action |\n| ------------------------------- | --------------------------------------- |\n| `Ctrl/Cmd + +` / `Ctrl/Cmd + =` | Zoom in |\n| `Ctrl/Cmd + -` | Zoom out |\n| `Ctrl/Cmd + 0` | Reset zoom (100%) |\n| `Space + Drag` | Pan canvas (when not in hand tool mode) |\n\n### Modifiers\n\n| Shortcut | Action |\n| ------------------- | -------------------------------------- |\n| `Shift + Drag` | Constrain proportions (drawing shapes) |\n| `Alt/Option + Drag` | Draw from center (shapes) |\n| `Ctrl/Cmd + Drag` | Duplicate while dragging |\n\n> **Note:** `Ctrl` is used on Windows/Linux, `Cmd` (ā) is used on macOS.\n\n## š Context Menu\n\nRight-click on the canvas or elements to access the context menu with quick actions:\n\n### Canvas Context Menu\n\n- **Paste** - Paste copied elements\n- **Select All** - Select all elements on canvas\n- **Clear Canvas** - Remove all elements\n\n### Element Context Menu\n\n- **Cut** - Cut selected element(s)\n- **Copy** - Copy selected element(s)\n- **Paste** - Paste from clipboard\n- **Duplicate** - Create a copy of selected element(s)\n- **Delete** - Remove selected element(s)\n- **Bring to Front** - Move to top layer\n- **Bring Forward** - Move one layer up\n- **Send to Back** - Move to bottom layer\n- **Send Backward** - Move one layer down\n\nThe context menu is context-aware and shows relevant options based on the current selection and clipboard state.\n\n## š¢ Whiteboard Events (Outputs)\n\nThe `NgWhiteboardComponent` emits the following events to notify about changes and interactions.\n\n### š¢ Lifecycle Events\n\n- **`ready`** Emitted when the whiteboard is fully initialized and ready for use.\n- **`destroyed`** Emitted when the whiteboard is destroyed, allowing for cleanup.\n\n### āļø Drawing Events\n\n- **`drawStart`** Triggered when a user starts drawing on the whiteboard.\n- **`drawing`** Emitted continuously while the user is drawing.\n- **`drawEnd`** Triggered when the user stops drawing.\n\n### š State & Data Events\n\n- **`undo`** Emitted when an undo action is performed.\n- **`redo`** Emitted when a redo action is performed.\n- **`clear`** Triggered when the whiteboard is cleared.\n- **`dataChange`** Emitted when the whiteboard's internal data state changes.\n- **`save`** Triggered when the whiteboard state is saved.\n\n### š Element Events\n\n- **`elementsAdded`** Emitted when a new element is added to the whiteboard.\n- **`elementsUpdated`** Triggered when an existing element is modified.\n- **`elementsSelected`** Emitted when an element is selected.\n- **`elementsDeleted`** Triggered when an element is removed.\n\n### š¼ Image Events\n\n- **`imageAdded`** Emitted when an image is added to the whiteboard.\n\n### š Configuration & Tool Events\n\n- **`selectedToolChange`** Triggered when the active drawing tool is changed.\n- **`configChanged`** Emitted when the whiteboard configuration settings are updated.\n\n## š¤ Contributing\n\nWe welcome contributions! Feel free to submit issues, feature requests, or pull requests.\n\n## š License\n\nThis project is licensed under the MIT License.\n","readmeFilename":"README.md"}
![](\"https://mostafazke.github.io/ng-whiteboard/assets/icons/icon-512x512.png\"){kind=icon}
\n \n