Configuration

async

Whether the canvas is rendered asynchronously. Asynchronous rendering does not block the UI and significantly improves performance when adding a large number of nodes and edges. However, it's important to note that some synchronous operations may produce unexpected results, such as getting the view of a node or getting the bounding box of nodes/edges, because these synchronous operations may be triggered before the asynchronous rendering is complete.

virtual

Whether to render only the elements in the visible area. Supports passing a boolean or an object VirtualOptions, default is false.

When set to the boolean value true, only the current visible area and the buffer margin (default: 120px) are rendered.

When an object VirtualOptions is provided:

• enabled: Whether to enable virtual rendering.
• margin: Buffer margin (px). Elements within this margin outside the viewport are pre-rendered to reduce repaint jitter during drag/zoom and improve interaction continuity.

Example:

new Graph({
  container: el,
  virtual: { enabled: true, margin: 200 },
})

When dragging, zooming the graph, or scrolling, the remaining elements are dynamically loaded based on the window size. This significantly improves performance in scenarios with a large number of elements.

magnetThreshold

The number of mouse movements required before triggering a connection, or set to 'onleave' to trigger a connection when the mouse leaves the element. Default is 0.

moveThreshold

The number of mouse movements allowed before triggering the 'mousemove' event, default is 0.

clickThreshold

When the number of mouse movements exceeds the specified number, the mouse click event will not be triggered. Default is 0.

preventDefaultContextMenu

Whether to disable the default right-click menu of the canvas, default is true.

preventDefaultBlankAction

Whether to disable the default mouse behavior when responding to mouse events in blank areas of the canvas, default is true.

onPortRendered

(
  this: Graph,
  args: {
    node: Node
    port: Port
    container: Element
    selectors?: Markup.Selectors
    labelContainer: Element
    labelSelectors?: Markup.Selectors
    contentContainer: Element
    contentSelectors?: Markup.Selectors
  },
) => void

Callback triggered when a port is rendered, with the following parameters:

For example, we can render a React-type port:

const graph = new Graph({
  container: this.container,
  onPortRendered(args) {
    const selectors = args.contentSelectors
    const container = selectors && selectors.foContent
    if (container) {
      ReactDOM.render(
        <Tooltip title="port">
          <div className="my-port" />
        </Tooltip>,
        container,
      )
    }
  },
})

onEdgeLabelRendered

type OnEdgeLabelRenderedArgs = {
  edge: Edge
  label: Edge.Label
  container: Element
  selectors: Markup.Selectors
}

(
  this: Graph,
  args: OnEdgeLabelRenderedArgs,
) => void | ((args: OnEdgeLabelRenderedArgs) => void)

The callback triggered when an edge label is rendered, And it can return a cleanup function, which will be executed when the label is destroyed, with the following parameters:

We can add a <foreignObject> element when defining the Label Markup to support HTML and React rendering capabilities.

const graph = new Graph({
  container: this.container,
  onEdgeLabelRendered: (args) => {
    const { selectors } = args
    const content = selectors.foContent as HTMLDivElement

    if (content) {
      content.style.display = 'flex'
      content.style.alignItems = 'center'
      content.style.justifyContent = 'center'
      ReactDOM.render(<Button size="small">Antd Button</Button>, content)
    }

    //  And it can return a cleanup function, which will be executed when the label is destroyed.
    return (edgeLabelRenderedArgs: typeof args) => {
      // Remove event listeners...
    }
  },
})


// The main purpose of this code is to test the cleanup function of onEdgeLabelRendered in a specific scenario.
const edge = graph.addEdge({
  source: [170, 160],
  target: [550, 160],
  labels: [
    {
      attrs: {
        text: {
          text: "Custom Label",
        },
      },
    },
  ],
});

setTimeout(() => {
  edge.prop("labels", ["Updated Label"]);
}, 2000);

createCellView

(this: Graph, cell: Cell) => CellView | null | undefined

Customize the view of an element. It can return a CellView to replace the default view. If it returns null, the element won't be rendered. If it returns undefined, the element will be rendered in the default way.

Methods

findView(...)

findView(ref: Cell | Element): CellView | null

Find the corresponding view based on the node/edge or element.

findViewByCell(...)

findViewByCell(cellId: string | number): CellView | null
findViewByCell(cell: Cell | null): CellView | null

Find the corresponding view based on the node/edge ID or instance.

findViewByElem(...)

findViewByElem(elem: string | Element | undefined | null): CellView | null

Find the corresponding view based on the element selector or element object.

findViewsFromPoint(...)

findViewsFromPoint(x: number, y: number): CellView[]
findViewsFromPoint(p: Point.PointLike): CellView[]

Return views of nodes/edges whose bounding boxes contain the specified point.

findViewsInArea(...)

findViewsInArea(
  x: number,
  y: number,
  width: number,
  height: number,
  options?: FindViewsInAreaOptions,
): CellView[]
findViewsInArea(
  rect: Rectangle.RectangleLike,
  options?: FindViewsInAreaOptions,
): CellView[]

Return views of nodes/edges whose bounding boxes intersect with the specified rectangle. When options.strict is true, the bounding box of the node/edge must completely contain the specified rectangle.

findViews(...)

findViews(ref: Point.PointLike | Rectangle.RectangleLike): CellView[]

Return views of nodes/edges whose bounding boxes contain the specified point or intersect with the specified rectangle.