Usage

We provide a standalone plugin package @antv/x6-plugin-selection to use the selection feature.

# npm
$ npm install @antv/x6-plugin-selection --save

# yarn
$ yarn add @antv/x6-plugin-selection

Then we use it in the code like this:

import { Selection } from '@antv/x6-plugin-selection'

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

Demo

• Click to select nodes.
• Enable multi-selection by holding down Ctrl/Command and clicking on nodes.
• Enable moving by dragging the selection box to move nodes.
• Enable rubberband selection by pressing the left mouse button on a blank area of the canvas and dragging the selection box to select nodes.
• Enable strict rubberband mode and observe its effect on selection.
• Use modifier keys in conjunction with selection, such as the alt key. Hold down the alt key and press the left mouse button on a blank area of the canvas to drag the selection box to select nodes.
• Apply a custom filter (exclude circle nodes), so that circular nodes cannot be selected.
• Apply custom additional content (display the number of selected nodes). Select two or more nodes to trigger the display of custom content.

Configuration

The type definition for Filter is as follows:

type Filter = string[] | { id: string }[] | (this: Graph, cell: Cell) => boolean

• string[]: An array of node shapes; only specified node/edge shapes can be selected.
• ({ id: string })[]: An array of node IDs; only specified nodes/edges can be selected.
• (this: Graph, cell: Cell) => boolean: Only nodes/edges that return true can be selected.

The type definition for ModifierKey is as follows:

type ModifierKey = string | ('alt' | 'ctrl' | 'meta' | 'shift')[] | null

The modifier keys in X6 include alt, ctrl, meta, and shift. After setting the modifier keys, you need to click the mouse and press the modifier keys to trigger the corresponding behavior. Modifier keys are very useful in certain scenarios, such as starting rubberband selection and dragging the canvas simultaneously, where both actions are triggered by pressing the left mouse button on a blank area of the canvas. You can set different modifier keys for rubberband selection and dragging the canvas to achieve simultaneous activation without conflict. You can configure a single (e.g., alt) or multiple (e.g., ['alt', 'ctrl']) modifier keys. Multiple modifier keys configured in array form are treated as an OR relationship. For example, the configured modifier keys indicate pressing alt or ctrl. If you need more flexible configurations, you can use the following forms:

• alt indicates pressing alt.
• [alt, ctrl] indicates pressing alt or ctrl.
• alt|ctrl indicates pressing alt or ctrl.
• alt&ctrl indicates pressing alt and ctrl simultaneously.
• alt|ctrl&shift indicates pressing alt and shift simultaneously or pressing ctrl and shift simultaneously.

The type definition for SelectionEventType is as follows:

type SelectionEventType = 'leftMouseDown' | 'mouseWheelDown';

Interaction methods that trigger rubberband selection. Supports two forms or combinations of them:

• leftMouseDown: Pressing the left mouse button to drag.
• mouseWheelDown: Pressing the mouse wheel to drag.

API

graph.select(...)

select(cells: Cell | string | (Cell | string)[]): this

Selects the specified nodes/edges. Note that this method does not unselect currently selected nodes/edges; it appends the specified nodes/edges to the selection. If you also need to unselect currently selected nodes/edges, please use the resetSelection(...) method.

graph.unselect(...)

unselect(cells: Cell | string | (Cell | string)[]): this

Unselects the specified nodes/edges.

graph.isSelected(...)

isSelected(cell: Cell | string): boolean

Returns whether the specified node/edge is selected.

graph.resetSelection(...)

resetSelection(cells?: Cell | string | (Cell | string)[]): this

Clears the selection first, then selects the provided nodes/edges.

graph.getSelectedCells()

getSelectedCells(): Cell[]

Gets the selected nodes/edges.

graph.cleanSelection()

cleanSelection(): this

Clears the selection.

graph.isSelectionEmpty()

cleanSelection(): boolean

Returns whether the selection is empty.

graph.isSelectionEnabled()

isSelectionEnabled(): boolean

Whether selection capability is enabled.

graph.enableSelection()

enableSelection(): this

Enables selection capability.

graph.disableSelection()

disableSelection(): this

Disables selection capability.

graph.toggleSelection(...)

toggleSelection(enabled?: boolean): this

Toggles the enabled state of selection. Parameters are as follows:

graph.isMultipleSelection()

isMultipleSelection(): boolean

Whether multi-selection is enabled.

graph.enableMultipleSelection()

enableMultipleSelection(): this

Enables multi-selection.

graph.disableMultipleSelection()

disableMultipleSelection(): this

Disables multi-selection.

graph.toggleMultipleSelection(...)

toggleMultipleSelection(multiple?: boolean): this

Toggles the enabled state of multi-selection. Parameters are as follows:

graph.isSelectionMovable()

isSelectionMovable(): boolean

Returns whether the selected nodes/edges can be moved.

graph.enableSelectionMovable()

enableSelectionMovable(): this

Enables moving of selected nodes/edges.

graph.disableSelectionMovable()

disableSelectionMovable(): this

Disables moving of selected nodes/edges.

graph.toggleSelectionMovable(...)

toggleSelectionMovable(enabled?: boolean): this

Toggles whether selected nodes/edges can be moved. Parameters are as follows:

graph.isRubberbandEnabled()

isRubberbandEnabled(): boolean

Returns whether rubberband selection is enabled.

graph.enableRubberband()

enableRubberband(): this

Enables rubberband selection.

graph.disableRubberband()

disableRubberband(): this

Disables rubberband selection.

graph.toggleRubberband(...)

toggleRubberband(enabled?: boolean): this

Toggles the enabled state of rubberband selection. Parameters are as follows:

graph.isStrictRubberband()

isStrictRubberband(): boolean

Returns whether strict rubberband selection is enabled. When strict rubberband selection is enabled, only nodes/edges that are completely enclosed by the selection box will be selected.

graph.enableStrictRubberband()

enableStrictRubberband(): this

Enables strict rubberband selection. When strict rubberband selection is enabled, only nodes/edges that are completely enclosed by the selection box will be selected.

graph.disableStrictRubberband()

disableStrictRubberband(): this

Disables strict rubberband selection. When strict rubberband selection is disabled, nodes/edges can be selected as long as the selection box intersects with their bounding box.

graph.toggleStrictRubberband(...)

toggleStrictRubberband(enabled?: boolean): this

Toggles the enabled state of strict rubberband selection. Parameters are as follows:

graph.setSelectionFilter(...)

setSelectionFilter(
  filter?:
   | null
   | (string | { id: string })[]
   | ((this: Graph, cell: Cell) => boolean)
): this

Sets the filtering criteria for selection; only nodes/edges that meet the filtering criteria can be selected.

graph.setRubberbandModifiers(...)

setRubberbandModifiers(modifiers?: string | ModifierKey[] | null): this

Sets the modifier keys for rubberband selection; rubberband selection can only be triggered when the modifier keys are pressed simultaneously.

graph.setSelectionDisplayContent(...)

setSelectionDisplayContent(
  content?:
   | null
   | false
   | string
   | ((this: Graph, selection: Selection, contentElement: HTMLElement) => string)
): this

Sets additional display content for selected nodes/edges.

Events

graph.on('node:selected', ({ node }) => {
  console.log(node)
})

// We can also listen to events on the plugin instance
selection.on('node:selected', ({ node }) => {
  console.log(node)
})