Skip to content
NgDiagram

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

Section titled “Available Actions”

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

ActionDefault ShortcutDescription
boxSelectionShift heldEnable box selection mode (pointer only)
cancelInteractionEscapeCancel the in-progress interaction (linking, drag, resize, rotate, pan) since v1.3.0
copyCtrl/Cmd + CCopy selected elements to clipboard
cutCtrl/Cmd + XCut selected elements to clipboard
deleteSelectionDelete or BackspaceDelete currently selected elements
keyboardMoveSelectionDown↓Move selected elements down
keyboardMoveSelectionLeft←Move selected elements left
keyboardMoveSelectionRight→Move selected elements right
keyboardMoveSelectionUp↑Move selected elements up
keyboardPanDown↓Pan viewport down
keyboardPanLeft←Pan viewport left
keyboardPanRight→Pan viewport right
keyboardPanUp↑Pan viewport up
keyboardZoomIn=Increase diagram viewport scale
keyboardZoomOut-Decrease diagram viewport scale
multiSelectionCtrl/Cmd heldMulti-selection mode (pointer only)
pasteCtrl/Cmd + VPaste elements from clipboard
redoCtrl/Cmd + YRedo last undone action (not implemented by default; requires custom model)
selectAllCtrl/Cmd + ASelect all elements in the diagram
undoCtrl/Cmd + ZUndo last action (not implemented by default; requires custom model)
zoomCtrl/Cmd + WheelIncrease or decrease diagram viewport scale

Arrow Keys: Move vs Pan

Section titled “Arrow Keys: Move vs Pan”

Each arrow key is bound to two actions: a keyboardMoveSelection action and a keyboardPan action (see the table above). Exactly one of them handles each key press:

  • The selection moves when node dragging is enabled (nodeDraggingEnabled) and at least one selected node is visible and draggable.
  • The viewport pans in every other case: nothing is selected, nodeDraggingEnabled is false, or the selection contains only hidden or draggable: false nodes. Panning requires viewportPanningEnabled.

A selection that cannot move never blocks the arrow keys.

Focus and Tab Order

Section titled “Focus and Tab Order”

Shortcuts only work when focus is inside the diagram. The diagram takes focus when the user clicks it, and it is also part of the page’s Tab order, so the user can reach it with the Tab key.

The diagram adds two Tab stops of its own: the diagram container and the watermark link.

Removing the Diagram from the Tab Order since v1.4.0

Section titled “Removing the Diagram from the Tab Order ”

If your application manages the focus on its own — for example with a roving tabindex on the nodes — set tabbable to false. Both Tab stops are then removed from the Tab order:

<ng-diagram [model]="model" [tabbable]="false" />
  • Both elements stay clickable and keep working with screen readers. Only the Tab stop is removed.
  • Shortcuts keep working once focus is inside the diagram, for example after a click.
  • Focusable content in your own node and edge templates is not affected. It keeps its own Tab stops, so the application stays in control of them.

Basic Usage

Section titled “Basic Usage”

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

import { configureShortcuts } from 'ng-diagram';


const config = {
  shortcuts: configureShortcuts([
    // Override: Change paste to Ctrl+B
    {
      actionName: 'paste',
      bindings: [{ key: 'b', modifiers: { primary: true } }],
    },
    // Disable: Empty bindings array
    {
      actionName: 'undo',
      bindings: [],
    },
    // Multiple bindings: WSAD + Arrow keys
    {
      actionName: 'keyboardMoveSelectionUp',
      bindings: [{ key: 'w' }, { key: 'ArrowUp' }],
    },
  ]),
};

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

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


// Merge custom shortcuts with existing ones
const updatedShortcuts = configureShortcuts(
  [
    {
      actionName: 'paste',
      bindings: [{ key: 'b', modifiers: { primary: true } }],
    },
  ],
  currentShortcuts // Pass existing shortcuts as base
);


// Update the configuration
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

Section titled “Configuration Reference”

Shortcut Structure

Section titled “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

Section titled “Available Modifiers”
interface InputModifiers {
  primary: boolean; // Ctrl (Windows/Linux) OR Cmd (macOS) - auto-normalized
  secondary: boolean; // Alt key
  shift: boolean; // Shift key
  meta: boolean; // Windows key or Cmd key
}

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

Section titled “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

Section titled “Modifier-Only Shortcuts”

Modifier-only shortcuts (bindings without a key) are used for pointer-based interactions, such as holding Shift for box selection or holding Ctrl/Cmd and using mouse wheel for zoom in and zoom out.

{
  modifiers: {
    shift: true,
  }
} // Matches when Shift held during click

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

Example

Section titled “Example”
import '@angular/compiler';
import { Component } from '@angular/core';
import { NgDiagramModelService, provideNgDiagram } from 'ng-diagram';
import { DiagramComponent } from './diagram.component';


@Component({
  imports: [DiagramComponent],
  template: `<shortcut-manager-example></shortcut-manager-example> `,
  styles: [
    `
      :host {
        display: flex;
        position: relative;
      }
    `,
  ],
  providers: [NgDiagramModelService, provideNgDiagram()],
})
export class DiagramWrapperComponent {}