Skip to content
X6

Scroller

View MarkdownResource indexEdit this page

In this chapter, we mainly introduce knowledge related to the scroller plugin. By reading, you can learn about

  • How to enable scrolling capabilities for the canvas

Note

The Scroller plugin disables the graph’s built-in panning by default to avoid interaction conflicts.

Usage

You can enable canvas scrolling with the Scroller plugin. For example:

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

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

Demo

import './index.less'
import { createRoot } from 'react-dom/client'
import React from 'react'
import { Button } from 'antd'
import { Graph, Scroller } from '@antv/x6'
import { Settings, State } from './settings.tsx'

const data = {
  hello: {
    id: 'hello',
    x: 32,
    y: 32,
    width: 100,
    height: 40,
    label: 'Hello',
    attrs: {
      body: {
        stroke: '#8f8f8f',
        strokeWidth: 1,
        fill: '#fff',
        rx: 6,
        ry: 6,
      },
    },
  },
  world: {
    id: 'world',
    shape: 'circle',
    x: 160,
    y: 180,
    width: 60,
    height: 60,
    label: 'World',
    attrs: {
      body: {
        stroke: '#8f8f8f',
        strokeWidth: 1,
        fill: '#fff',
      },
    },
  },
  rect: {
    id: 'rect',
    x: -60,
    y: 100,
    width: 100,
    height: 40,
    label: 'Rect',
    attrs: {
      body: {
        stroke: '#8f8f8f',
        strokeWidth: 1,
        fill: '#fff',
        rx: 6,
        ry: 6,
      },
    },
  },
}

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

  componentDidMount() {
    this.renderGraph()
  }

  renderGraph(options: State | null = null) {
    if (this.graph) {
      this.graph.dispose()
    }

    const graph = new Graph({
      container: this.container,
      panning: false,
      background: {
        color: '#F2F7FA',
      },
    })
    graph.use(
      new Scroller({
        enabled: true,
        pageVisible: true,
        pageBreak: true,
        pannable: true,
        ...options,
      }),
    )

    graph.fromJSON({ nodes: Object.keys(data).map((key) => data[key]) })

    graph.on('node:change:position', ({ node, current }) => {
      const item = data[node.id]
      item.x = current!.x
      item.y = current!.y
    })

    graph.centerContent()
    this.graph = graph
  }

  onSettingsChanged = (options: State) => {
    this.renderGraph(options)
  }

  onCenter = () => {
    this.graph.center()
  }

  onCenterContent = () => {
    this.graph.centerContent()
  }

  onCenterCircle = () => {
    const circle = this.graph.getCellById('world')
    if (circle) {
      this.graph.centerCell(circle)
    }
  }

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

  render() {
    return (
      <div className="scroller-app">
        <div className="app-side">
          <Settings onChange={this.onSettingsChanged} />
        </div>
        <div className="app-main">
          <div className="app-btns">
            <Button onClick={this.onCenter}>Center Graph</Button>
            <Button onClick={this.onCenterContent}>Center Whole Content</Button>
            <Button onClick={this.onCenterCircle}>Center The Circle</Button>
          </div>
          <div className="app-content" ref={this.refContainer} />
        </div>
      </div>
    )
  }
}

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

Options

Property Name Type Default Required Description
pannable boolean false Whether to enable canvas panning capability (dragging the canvas after pressing the mouse on a blank area)
className string - Additional class name for custom styling
width number - Width of the Scroller, defaults to the width of the canvas container
height number - Height of the Scroller, defaults to the height of the canvas container
modifiers ModifierKey - Set modifier keys that need to be pressed along with the mouse click to trigger canvas dragging
pageWidth number - Width of each page, defaults to the width of the canvas container
pageHeight number - Height of each page, defaults to the height of the canvas container
pageVisible boolean false Whether to enable pagination
pageBreak boolean false Whether to show page breaks
autoResize boolean true Whether to automatically expand/shrink the canvas. When enabled, moving nodes/edges will automatically calculate the required canvas size, expanding it according to pageWidth and pageHeight when exceeding the current size, and shrinking it otherwise.
minVisibleWidth number - Effective when padding is empty, sets the minimum visible width of the canvas during scrolling
minVisibleHeight number - Effective when padding is empty, sets the minimum visible height of the canvas during scrolling
padding number | Padding - Sets the padding around the canvas. Defaults to being automatically calculated based on minVisibleWidth and minVisibleHeight, ensuring that at least minVisibleWidth and minVisibleHeight of the canvas is visible during scrolling.

The Padding type is defined as follows:

type Padding = { top: number; right: number; bottom: number; left: number }

The ModifierKey type is defined as follows:

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

Supports the following forms:

  • alt means pressing alt.
  • [alt, ctrl] means pressing either alt or ctrl.
  • alt|ctrl means pressing either alt or ctrl.
  • alt&ctrl means pressing both alt and ctrl simultaneously.
  • alt|ctrl&shift means pressing both alt and shift simultaneously or both ctrl and shift simultaneously.

API

graph.lockScroller()

Disables scrolling.

graph.unlockScroller()

Enables scrolling.

graph.getScrollbarPosition()

Gets the scrollbar position.

graph.setScrollbarPosition(left?: number, top?: number)

Sets the scrollbar position.

  • left?: number The position of the horizontal scrollbar; defaults to no horizontal scrolling.
  • top?: number The position of the vertical scrollbar; defaults to no vertical scrolling.

For example:

graph.setScrollbarPosition(100)
graph.setScrollbarPosition(100, null)
graph.setScrollbarPosition(null, 200)
graph.setScrollbarPosition(100, 200)
© Copyright 2026 Ant Group Co., Ltd..备案号：京ICP备15032932号-38
Site search
Documentation and examplesType to start searching

Search documentation, APIs, and examples

↑↓Select↵OpenEscClose