Skip to content

Keyboard

This section mainly introduces the Keyboard plugin. By reading, you will learn:

  • How to bind keyboard shortcuts on the canvas

Usage

Enable keyboard shortcuts via the Keyboard plugin:

import { Graph, Keyboard } from '@antv/x6'

const graph = new Graph({
  background: {
    color: '#F2F7FA',
  },
})
graph.use(
  new Keyboard({
    enabled: true,
  }),
)

Demo

import './index.less'
import { createRoot } from 'react-dom/client'
import * as React from 'react'
import { Graph, Clipboard, Keyboard, Selection } from '@antv/x6'

export default class Example extends React.Component {
  private container: HTMLDivElement
  private graph: Graph

  componentDidMount() {
    this.graph = new Graph({
      container: this.container,
      background: {
        color: '#F2F7FA',
      },
    })

    this.graph.use(
      new Clipboard({
        enabled: true,
      }),
    )
    this.graph.use(
      new Selection({
        enabled: true,
        showNodeSelectionBox: true,
      }),
    )
    this.graph.use(
      new Keyboard({
        enabled: true,
        global: true,
      }),
    )

    this.graph.addNode({
      x: 280,
      y: 100,
      width: 100,
      height: 40,
      label: 'Rect',
      attrs: {
        body: {
          stroke: '#8f8f8f',
          strokeWidth: 1,
          fill: '#fff',
          rx: 6,
          ry: 6,
        },
      },
    })

    const source = this.graph.addNode({
      x: 32,
      y: 32,
      width: 100,
      height: 40,
      label: 'Hello',
      attrs: {
        body: {
          stroke: '#8f8f8f',
          strokeWidth: 1,
          fill: '#fff',
          rx: 6,
          ry: 6,
        },
      },
    })

    const target = this.graph.addNode({
      shape: 'circle',
      x: 160,
      y: 180,
      width: 60,
      height: 60,
      label: 'World',
      attrs: {
        body: {
          stroke: '#8f8f8f',
          strokeWidth: 1,
          fill: '#fff',
        },
      },
    })

    this.graph.addEdge({
      source,
      target,
      attrs: {
        line: {
          stroke: '#8f8f8f',
          strokeWidth: 1,
        },
      },
    })

    this.graph.bindKey('ctrl+c', () => {
      const cells = this.graph.getSelectedCells()
      if (cells.length) {
        this.graph.copy(cells)
      }
      return false
    })

    this.graph.bindKey('ctrl+v', () => {
      if (!this.graph.isClipboardEmpty()) {
        const cells = this.graph.paste({ offset: 32 })
        this.graph.cleanSelection()
        this.graph.select(cells)
      }
      return false
    })
  }

  refContainer = (container: HTMLDivElement) => {
    this.container = container
  }

  render() {
    return (
      <div className="keyboard-app">
        <div className="app-info">
          <p>
            <span>Ctrl + C</span>Copy Cell
            <span style={{ marginLeft: 24 }}>Ctrl + V</span>Paste Cell
          </p>
        </div>
        <div className="app-content" ref={this.refContainer} />
      </div>
    )
  }
}

const root = createRoot(document.getElementById('container')!)
root.render(<Example />)
window.addEventListener('pagehide', () => root.unmount(), { once: true })

Configuration

Property Name Type Default Value Required Description
global boolean false Whether to use global keyboard events. When set to true, keyboard events are bound to document; otherwise they are bound to the canvas container. When bound to the canvas container, it must be focused to trigger keyboard events.
format (this: Graph, key: string) => string - Format the key string when binding or unbinding keyboard events.
guard (this: Graph, e: KeyboardEvent) => boolean - Determine whether a keyboard event should be processed. If it returns false, the corresponding keyboard event is ignored.

The format and guard configurations are used as follows:

graph.use(
  new Keyboard({
    enabled: true,
    format(key) {
      return key.replace(/\s/g, '').replace('cmd', 'command')
    },
  }),
)
// The statement below is equivalent to graph.bindKey('command', (e) => { })
graph.bindKey('cmd', (e) => {})

graph.use(
  new Keyboard({
    enabled: true,
    guard(this: Graph, e: KeyboardEvent) {
      if (e.altKey) {
        // Ignore all keyboard events when the alt key is pressed
        return false
      }
      return true
    },
  }),
)

API

graph.bindKey(…)

bindKey(
  keys: string | string[],
  callback: (e: KeyboardEvent) => void,
  action?: 'keypress' | 'keydown' | 'keyup',
): this

Bind keyboard shortcuts.

graph.unbindKey(…)

unbindKey(
  keys: string | string[],
  action?: 'keypress' | 'keydown' | 'keyup',
): this

Unbind keyboard shortcuts.

graph.clearKeys()

clearKeys(): this

Clear all keyboard shortcuts.

graph.triggerKey()

triggerKey(
  keys: string,
  action?: 'keypress' | 'keydown' | 'keyup',
): this

Manually trigger keyboard shortcuts.

graph.isKeyboardEnabled()

isKeyboardEnabled(): boolean

Returns whether keyboard events are enabled.

graph.enableKeyboard()

enableKeyboard(): this

Enable keyboard events.

graph.disableKeyboard()

disableKeyboard(): this

Disable keyboard events.

graph.toggleKeyboard(…)

toggleKeyboard(enabled?: boolean): this

Toggle the enabled state of keyboard events. The parameters are as follows:

Name Type Required Default Value Description
enabled boolean - Whether to enable keyboard events; if omitted, toggles the current enabled state.
© Copyright 2026 Ant Group Co., Ltd..备案号:京ICP备15032932号-38
Site search
Documentation and examplesType to start searching

Search documentation, APIs, and examples

↑↓Select↵OpenEscClose