Keyboard Shortcuts

The keyboard shortcuts system in ngDiagram lets users perform common actions quickly using customizable key combinations. It supports platform-specific modifier keys (automatically handling Ctrl/Cmd differences), multiple shortcuts per action, and dynamic runtime updates.

Available Actions

All available shortcut actions with their default key bindings. See ShortcutActionName for the complete type reference.

Action	Default Shortcut	Description
`copy`	`Ctrl/Cmd + C`	Copy selected elements to clipboard
`cut`	`Ctrl/Cmd + X`	Cut selected elements to clipboard
`paste`	`Ctrl/Cmd + V`	Paste elements from clipboard
`deleteSelection`	`Delete` or `Backspace`	Delete currently selected elements
`selectAll`	`Ctrl/Cmd + A`	Select all elements in the diagram
`boxSelection`	`Shift` held	Enable box selection mode (pointer only)
`multiSelection`	`Ctrl/Cmd` held	Multi-selection mode (pointer only)
`keyboardMoveSelectionUp`	`↑`	Move selected elements up
`keyboardMoveSelectionDown`	`↓`	Move selected elements down
`keyboardMoveSelectionLeft`	`←`	Move selected elements left
`keyboardMoveSelectionRight`	`→`	Move selected elements right
`keyboardPanUp`	`↑`	Pan viewport up
`keyboardPanDown`	`↓`	Pan viewport down
`keyboardPanLeft`	`←`	Pan viewport left
`keyboardPanRight`	`→`	Pan viewport right
`undo`	`Ctrl/Cmd + Z`	Undo last action (not implemented by default; requires custom model)
`redo`	`Ctrl/Cmd + Y`	Redo last undone action (not implemented by default; requires custom model)

Basic Usage

To override, disable, or extend default shortcuts, use the configureShortcuts() helper:

1
import { configureShortcuts } from 'ng-diagram';
2

3
const config = {
4
  shortcuts: configureShortcuts([
5
    // Override: Change paste to Ctrl+B
6
    {
7
      actionName: 'paste',
8
      bindings: [{ key: 'b', modifiers: { primary: true } }],
9
    },
10
    // Disable: Empty bindings array
11
    {
12
      actionName: 'undo',
13
      bindings: [],
14
    },
15
    // Multiple bindings: WSAD + Arrow keys
16
    {
17
      actionName: 'keyboardMoveSelectionUp',
18
      bindings: [{ key: 'w' }, { key: 'ArrowUp' }],
19
    },
20
  ]),
21
};

You can also merge custom shortcuts with existing ones at runtime:

1
// Get current shortcuts from the service
2
const currentShortcuts = ngDiagramService.config().shortcuts;
3

4
// Merge custom shortcuts with existing ones
5
const updatedShortcuts = configureShortcuts(
6
  [
7
    {
8
      actionName: 'paste',
9
      bindings: [{ key: 'b', modifiers: { primary: true } }],
10
    },
11
  ],
12
  currentShortcuts // Pass existing shortcuts as base
13
);
14

15
// Update the configuration
16
ngDiagramService.updateConfig({ shortcuts: updatedShortcuts });

configureShortcuts(customShortcuts, baseShortcuts?) merges your custom shortcuts with defaults:

First parameter: Custom shortcuts (overrides actions with matching actionName)
Second parameter: Optional base shortcuts. Defaults are used if omitted.
Returns: A merged shortcuts array

Unspecified actions retain their existing shortcuts.

Configuration Reference

Shortcut Structure

Keyboard and pointer shortcuts in ngDiagram are defined through the ShortcutDefinition interface. A shortcut definition maps an action name to one or more key bindings (keyboard or modifier-only combinations).

Each shortcut may include:

One or more keyboard bindings (e.g., Ctrl + C)
Or one or more modifier-only bindings (e.g., Shift + click for box selection)

See ShortcutDefinition API reference.

Available Modifiers

1
interface InputModifiers {
2
  primary: boolean; // Ctrl (Windows/Linux) OR Cmd (macOS) - auto-normalized
3
  secondary: boolean; // Alt key
4
  shift: boolean; // Shift key
5
  meta: boolean; // Windows key or Cmd key
6
}

Platform normalization:

The primary modifier automatically maps to Ctrl on Windows/Linux and Cmd on macOS, allowing you to define shortcuts once that work seamlessly across platforms.

Key Names

Use standard browser key names: 'a', 'b', 'Delete', 'Backspace', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', etc. Keys are case-sensitive.

See MDN KeyboardEvent.key documentation for the complete list of valid key values.

Modifier-Only Shortcuts

Modifier-only shortcuts (bindings without a key) are used for pointer-based interactions, such as holding Shift for box selection.

1
{
2
  modifiers: {
3
    shift: true,
4
  }
5
} // Matches when Shift held during click

These shortcuts ensure that typing keys won’t accidentally trigger diagram actions.

Example

1
import '@angular/compiler';
2
import { Component } from '@angular/core';
3
import { NgDiagramModelService, provideNgDiagram } from 'ng-diagram';
4
import { DiagramComponent } from './diagram.component';
5

6
@Component({
7
  imports: [DiagramComponent],
8
  template: `<shortcut-manager-example></shortcut-manager-example> `,
9
  styles: [
10
    `
11
      :host {
12
        display: flex;
13
        position: relative;
14
      }
15
    `,
16
  ],
17
  providers: [NgDiagramModelService, provideNgDiagram()],
18
})
19
export class DiagramWrapperComponent {}

1
import '@angular/compiler';
2
import { Component } from '@angular/core';
3
import {
4
  configureShortcuts,
5
  initializeModel,
6
  NgDiagramBackgroundComponent,
7
  NgDiagramComponent,
8
  NgDiagramViewportService,
9
  type NgDiagramConfig,
10
} from 'ng-diagram';
11
import { ShortcutButtonsComponent } from './shortcut-buttons/shortcut-buttons.component';
12

13
@Component({
14
  selector: 'shortcut-manager-example',
15
  imports: [
16
    NgDiagramComponent,
17
    NgDiagramBackgroundComponent,
18
    ShortcutButtonsComponent,
19
  ],
20
  template: `
21
    <div class="not-content diagram">
22
      <ng-diagram [model]="model" [config]="config">
23
        <ng-diagram-background />
24
      </ng-diagram>
25
    </div>
26
    <shortcut-buttons />
27
  `,
28
  styleUrl: './diagram.component.scss',
29
  providers: [NgDiagramViewportService],
30
})
31
export class DiagramComponent {
32
  config = {
33
    zoom: {
34
      zoomToFit: {
35
        onInit: true,
36
        padding: 100,
37
      },
38
    },
39
    shortcuts: configureShortcuts([
40
      // Custom keyboard shortcuts for moving selection
41
      {
42
        actionName: 'keyboardMoveSelectionUp',
43
        bindings: [{ key: 'w' }, { key: 'ArrowUp' }],
44
      },
45
      {
46
        actionName: 'keyboardMoveSelectionDown',
47
        bindings: [{ key: 's' }, { key: 'ArrowDown' }],
48
      },
49
      {
50
        actionName: 'keyboardMoveSelectionLeft',
51
        bindings: [{ key: 'a' }, { key: 'ArrowLeft' }],
52
      },
53
      {
54
        actionName: 'keyboardMoveSelectionRight',
55
        bindings: [{ key: 'd' }, { key: 'ArrowRight' }],
56
      },
57
    ]),
58
  } satisfies NgDiagramConfig;
59

60
  model = initializeModel({
61
    nodes: [
62
      {
63
        id: '1',
64
        position: { x: 100, y: 100 },
65
        data: {
66
          label: 'Node 1',
67
        },
68
      },
69
      {
70
        id: '2',
71
        position: { x: 400, y: 100 },
72
        data: {
73
          label: 'Node 2',
74
        },
75
      },
76
      {
77
        id: '3',
78
        position: { x: 250, y: 300 },
79
        data: {
80
          label: 'Node 3',
81
        },
82
      },
83
    ],
84
  });
85
}

1
import { Component, inject, signal } from '@angular/core';
2
import {
3
  configureShortcuts,
4
  NgDiagramService,
5
  type ShortcutDefinition,
6
} from 'ng-diagram';
7

8
@Component({
9
  imports: [],
10
  selector: 'shortcut-buttons',
11
  template: `
12
    <label class="checkbox-label">
13
      <input
14
        type="checkbox"
15
        [checked]="useCustomShortcut()"
16
        (change)="togglePasteShortcut()"
17
      />
18
      <span>Use Ctrl/Cmd + B for paste</span>
19
    </label>
20
  `,
21
  styleUrls: ['./shortcut-buttons.component.scss'],
22
})
23
export class ShortcutButtonsComponent {
24
  private readonly ngDiagramService = inject(NgDiagramService);
25
  protected readonly useCustomShortcut = signal(false);
26

27
  togglePasteShortcut(): void {
28
    this.useCustomShortcut.update((value) => !value);
29

30
    const currentShortcuts = this.ngDiagramService.config()
31
      .shortcuts as ShortcutDefinition[];
32
    const updatedShortcuts = configureShortcuts(
33
      [
34
        {
35
          actionName: 'paste',
36
          bindings: [
37
            {
38
              key: this.useCustomShortcut() ? 'b' : 'v',
39
              modifiers: { primary: true },
40
            },
41
          ],
42
        },
43
      ],
44
      currentShortcuts
45
    );
46

47
    this.ngDiagramService.updateConfig({
48
      shortcuts: updatedShortcuts,
49
    });
50
  }
51
}

1
:host {
2
  position: relative;
3
  width: 100%;
4
  height: 100%;
5
  display: block; // needed for flex children to work, otherwise children renders outside of host
6
}
7

8
.diagram {
9
  display: flex;
10
  height: var(--ng-diagram-height);
11
  border: var(--ng-diagram-border);
12
  margin-top: 0;
13
}

1
:host {
2
  position: absolute;
3
  right: 1rem;
4
  top: 1rem;
5
  display: flex;
6
  background-color: var(--ngd-node-bg-primary-default);
7
  border: var(--ng-diagram-border);
8
  margin-top: 0;
9

10
  .checkbox-label {
11
    display: flex;
12
    align-items: center;
13
    gap: 0.5rem;
14
    padding: 0.5rem 0.75rem;
15
    border-radius: 0.25rem;
16
    user-select: none;
17
    cursor: pointer;
18

19
    input[type='checkbox'] {
20
      width: 1rem;
21
      height: 1rem;
22
      cursor: pointer;
23
    }
24

25
    span {
26
      font-size: 0.875rem;
27
    }
28
  }
29
}