Overview of the Event System

G6 provides a powerful event mechanism that allows you to respond to various interactive behaviors occurring in the chart, such as node clicks, edge hovers, canvas drags, etc. Through the event system, you can implement complex interactive logic to enhance user experience.

Event Categories

Events in G6 can be broadly categorized into the following types:

1. Element Events: Events related to nodes, edges, and Combos, such as node:click, edge:mouseenter
2. Canvas Events: Events related to the entire canvas, such as canvas:drag, canvas:zoom
3. Lifecycle Events: Events related to the chart lifecycle, such as beforerender, afterrender

Event Naming Convention

G6 events follow the [object]:[event] format, for example:

• node:click - Node click event
• edge:mouseenter - Mouse enters edge event
• canvas:drag - Canvas drag event

Best Practice: Using Constant Enums

G6 provides a complete set of event constant enums, and it is strongly recommended to use these constants instead of directly using string event names:

import { NodeEvent, EdgeEvent, CanvasEvent, GraphEvent } from '@antv/g6';

// Use constant enums to listen to events
graph.on(NodeEvent.CLICK, handleNodeClick);
graph.on(EdgeEvent.POINTER_OVER, handleEdgeHover);
graph.on(CanvasEvent.DRAG, handleCanvasDrag);
graph.on(GraphEvent.AFTER_RENDER, handleAfterRender);

Advantages:

• Type safety, avoiding string spelling errors
• Provides intelligent code hints and auto-completion

API Reference

Graph.on(eventName, callback, once)

Listen to a specified event and execute a callback function when the event is triggered.

on<T extends IEvent = IEvent>(eventName: string, callback: (event: T) => void, once?: boolean): this;

Parameters

Return Value

• Type: this (Graph instance)
• Description: Returns the graph instance itself, supporting chain calls

Example

import { NodeEvent, EdgeEvent, CanvasEvent } from '@antv/g6';

// Listen to node click event
graph.on(NodeEvent.CLICK, (evt) => {
  const { target } = evt; // Get the ID of the clicked node
  console.log(`Node ${target.id} was clicked`);

  // Get node data
  const nodeData = graph.getNodeData(target.id);
  console.log('Node data:', nodeData);

  // Modify node state
  graph.setElementState(target.id, 'selected');
});

// Listen to edge mouse enter event
graph.on(EdgeEvent.POINTER_OVER, (evt) => {
  const { target } = evt;
  graph.setElementState(target.id, 'highlight');
});

// Listen to canvas drag event
graph.on(CanvasEvent.DRAG, (evt) => {
  console.log('Canvas is being dragged');
});

Graph.once(eventName, callback)

Listen to an event once, and automatically remove the listener after the event is triggered once.

once<T extends IEvent = IEvent>(eventName: string, callback: (event: T) => void): this;

Parameters

Return Value

• Type: this (Graph instance)
• Description: Returns the graph instance itself, supporting chain calls

Example

import { GraphEvent, NodeEvent } from '@antv/g6';

// Listen to the chart's first load completion event, executed only once
graph.once(GraphEvent.AFTER_RENDER, () => {
  console.log('Chart rendered for the first time');
  // Execute one-time initialization operations
  highlightImportantNodes();
});

// Wait for the user to click a node for the first time and then perform operations
graph.once(NodeEvent.CLICK, (evt) => {
  console.log('User clicked a node for the first time:', evt.target.id);
  showTutorialTip('You can drag nodes to change their position');
});

Graph.off()

Remove all event listeners.

off(): this;

Return Value

• Type: this (Graph instance)
• Description: Returns the graph instance itself, supporting chain calls

Example

// Remove all event listeners
graph.off();
console.log('All event listeners have been removed');

Graph.off(eventName)

Remove all listeners of a specified event type.

off(eventName: string): this;

Parameters

Return Value

• Type: this (Graph instance)
• Description: Returns the graph instance itself, supporting chain calls

Example

import { NodeEvent } from '@antv/g6';

// Remove all node click event listeners
graph.off(NodeEvent.CLICK);
console.log('All node click event listeners have been removed');

// Remove related temporary event listeners after a certain operation mode ends
function exitEditMode() {
  // Remove all listeners in edit mode
  graph.off(NodeEvent.DRAG_END);
  graph.off(NodeEvent.DROP);
  console.log('Exited edit mode');
}

Graph.off(eventName, callback)

Remove a specific callback function for a specific event.

off(eventName: string, callback: (...args: any[]) => void): this;

Parameters

Return Value

• Type: this (Graph instance)
• Description: Returns the graph instance itself, supporting chain calls

Example

import { NodeEvent } from '@antv/g6';

// Define callback function
const handleNodeClick = (evt) => {
  console.log('Node clicked:', evt.target.id);
};

// Add listener
graph.on(NodeEvent.CLICK, handleNodeClick);

// Later, remove this specific listener at a certain point
graph.off(NodeEvent.CLICK, handleNodeClick);
console.log('Specific node click event listener has been removed');

Event Constant Enums

G6 provides various event constant enums to facilitate developers in using standardized event names. Below is a detailed description of all event constants:

Node Events (NodeEvent)

Edge Events (EdgeEvent)

Combo Events (ComboEvent)

Canvas Events (CanvasEvent)

Graph Lifecycle Events (GraphEvent)

Container Events (ContainerEvent)

Common Events (CommonEvent)

These are events without prefixes and can be used to listen to global events:

Tips for Use

Chain Calls

G6's event API supports chain calls, allowing you to register multiple events consecutively:

import { NodeEvent, EdgeEvent, CanvasEvent } from '@antv/g6';

// Use constant enums + chain calls
graph.on(NodeEvent.CLICK, handleNodeClick).on(EdgeEvent.CLICK, handleEdgeClick).on(CanvasEvent.WHEEL, handleCanvasZoom);

Event Delegation

You can use the event bubbling mechanism to listen to all child element events on the parent element:

import { CommonEvent } from '@antv/g6';

// Handle all element click events uniformly
graph.on(CommonEvent.CLICK, (evt) => {
  const { targetType, target } = evt;
  if (targetType === 'node') {
    console.log('Clicked on node:', target.id);
  } else if (targetType === 'edge') {
    console.log('Clicked on edge:', target.id);
  } else {
    console.log('Clicked on canvas blank area');
  }
});

Event Object Properties

Most event callback functions receive an event object containing the following common properties:

• target - The element that triggered the event
• targetType - The type of the element that triggered the event (node/edge/combo/canvas)
• originalTarget - The original graphic that triggered the event
• currentTarget - The current object that triggered the event
• originalEvent - The original browser event object

With these properties, you can precisely control interactive behavior.