Scroll settings in React Diagram component

27 Oct 202424 minutes to read

The diagram can be scrolled using both the vertical and horizontal scrollbars. Additionally, the mouse wheel can be used to scroll the diagram. The diagram’s scrollSettings allow you to read the current scroll status, view port size, current zoom level, and zoom factor. These settings also provide the capability to programmatically control the scrolling of the diagram.

Access and Customize Scroll Settings

Scroll settings in a diagram allow you to access and customize various properties such as horizontalOffset, verticalOffset, viewPortWidth, viewPortHeight, currentZoom, zoomFactor, maxZoom, minZoom, scrollLimit, canAutoScroll, autoScrollBorder, padding, scrollableArea.

These properties enable you to read and adjust the scroll status, scroll offset, zoom levels, and more. For a comprehensive overview of these properties, refer to the Scroll Settings

Define scroll offset

The diagram allows you to pan before loading, ensuring that any desired region of a large diagram is visible. You can programmatically pan the diagram using the horizontalOffset and verticalOffset properties of the scroll settings. The following code illustrates how to programmatically pan the diagram upon initialization also defined scrollLimit as ‘Infinity’ to scroll infinitely in diagram. To learn more about scrollLimit refer to scrollLimit

In the example below, the vertical scrollbar is scrolled down by 100 px, and the horizontal scrollbar is scrolled to the right by 100 px.

import * as React from "react";
import * as ReactDOM from "react-dom";
import { DiagramComponent } from "@syncfusion/ej2-react-diagrams";
//Sets scroll status
let diagramInstance;
function App() {
    return (<DiagramComponent id="container" ref={(diagram) => (diagramInstance = diagram)} width={700} height={700} rulerSettings= scrollSettings=
        created={() => {
            diagramInstance.scrollSettings.horizontalOffset = 100;
            diagramInstance.scrollSettings.verticalOffset = 100;
            diagramInstance.dataBind();
        }}/>);
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);
import * as React from "react";
import * as ReactDOM from "react-dom";
import {
    DiagramComponent
} from "@syncfusion/ej2-react-diagrams";
//Sets scroll status
let diagramInstance: DiagramComponent;
function App() {
  return (
    <DiagramComponent
      id="container"
      ref={(diagram) => (diagramInstance = diagram)}
      width={700}
      height={700}
      rulerSettings=
      scrollSettings=
      created={() => {
        diagramInstance.scrollSettings.horizontalOffset = 100;
        diagramInstance.scrollSettings.verticalOffset = 100;
        diagramInstance.dataBind();
      }}
    />
  );
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);

Update scroll offset at runtime

There are several ways to update the scroll offset at runtime:

  • Scrollbar: Use the horizontal and vertical scrollbars of the diagram.
  • Mousewheel: Scroll vertically with the mouse wheel. Hold the Shift key while scrolling to scroll horizontally.
  • Pan Tool: Activate the ZoomPan tool in the diagram to scroll by panning.
  • Touch: Use touch pad gestures for scrolling.

Programmatically update Scroll Offset

You can programmatically change the scroll offsets of diagram by customizing the horizontalOffset and verticalOffset of Scroll Settings at runtime. The following code illustrates how to change the scroll offsets at runtime.

import * as React from "react";
import * as ReactDOM from "react-dom";
import { DiagramComponent } from "@syncfusion/ej2-react-diagrams";
let diagramInstance;
let node = [{
    offsetX: 300,
    offsetY: 300
}]
function App() {
    const updateOffset = () => {
        diagramInstance.scrollSettings.horizontalOffset = 200;
        diagramInstance.scrollSettings.verticalOffset = 100;
        diagramInstance.dataBind();
    };  
    return (
    <div>
        <button id="updateOffset" onClick={updateOffset}>Update Scroller Offset</button>
        <DiagramComponent id="container" ref={(diagram) => (diagramInstance = diagram)} width={700} height={700} nodes={node} rulerSettings= scrollSettings=/>
    </div>);
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);
import * as React from "react";
import * as ReactDOM from "react-dom";
import {
    NodeModel,
    DiagramComponent
} from "@syncfusion/ej2-react-diagrams";
let diagramInstance: DiagramComponent;
let node: NodeModel[] = [{
  offsetX: 300,
  offsetY: 300,
}];
function App() {
  const updateOffset = () => {
    diagramInstance.scrollSettings.horizontalOffset = 200;
    diagramInstance.scrollSettings.verticalOffset = 100;
    diagramInstance.dataBind();
  }; 
  return (
    <div>
      <button id="updateOffset" onClick={updateOffset}>Update Scroller Offset</button>
      <DiagramComponent
        id="container"
        ref={(diagram) => (diagramInstance = diagram)}
        width={700}
        height={700}
        nodes={node}
        rulerSettings=
        scrollSettings=
      />
    </div>
  );
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);

Update zoom at runtime

Zoom using mouse wheel

Another way to zoom in and out the diagram is by using the mouse wheel. This method is a quick and convenient way to zoom in and out without having to use any additional tools or gestures.

  • Zoom in: Press Ctrl+mouse wheel, then scroll upward.

  • Zoom out: Press Ctrl+mouse wheel, then scroll downward.

Zoom using Keyboard Shortcuts

Using keyboard shortcuts is a quick and easy way to zoom the diagram without having to use the mouse or touch pad.

  • Zoom in: Press Ctrl and the plus(+) key.

  • Zoom out: Press Ctrl and the minus(-) key.

Programmatically update zoom

You can programmatically change the current zoom of diagram by utilizing the zoomTo public method.

ZoomOptions

The zoomTo method takes one parameter zoomOptions. In that zoomOptions we can specify the focusPoint, type and zoomFactor

The following example shows how to zoom-in and zoom-out the diagram using zoomTo method

import * as React from "react";
import * as ReactDOM from "react-dom";
import { DiagramComponent } from "@syncfusion/ej2-react-diagrams";
let diagramInstance;
let node = [{
    offsetX: 300,
    offsetY: 300
}]
function App() {
    const zoomIn = () => {
        let zoomOptions = {
            type: 'ZoomIn',
            zoomFactor: 0.2,
            focusPoint: { x: 0.5, y: 0.5 },
        };
        diagramInstance.zoomTo(zoomOptions);
        diagramInstance.dataBind();
    };
    const zoomOut = () => {
        let zoomOptions = {
            type: 'ZoomOut',
            zoomFactor: 0.2,
            focusPoint: { x: 0.5, y: 0.5 },
        };
        diagramInstance.zoomTo(zoomOptions);
        diagramInstance.dataBind();
    };  
    return (
    <div>
        <button id="zoomIn" onClick={zoomIn}>Zoom In</button>
        <button id="zoomOut" onClick={zoomOut}>Zoom Out</button>
        <DiagramComponent id="container" ref={(diagram) => (diagramInstance = diagram)} width={700} height={700} nodes={node} rulerSettings= scrollSettings=/>
    </div>);
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);
import * as React from "react";
import * as ReactDOM from "react-dom";
import {
    NodeModel,
    DiagramComponent,
    ZoomOptions
} from "@syncfusion/ej2-react-diagrams";
let diagramInstance: DiagramComponent;
let node: NodeModel[] = [{
  offsetX: 300,
  offsetY: 300,
}];
function App() {
  const zoomIn = () => {
    let zoomOptions: ZoomOptions = {
        type: 'ZoomIn',
        zoomFactor: 0.2,
        focusPoint: { x: 0.5, y: 0.5 },
    };
    diagramInstance.zoomTo(zoomOptions);
    diagramInstance.dataBind();
  };
const zoomOut = () => {
    let zoomOptions: ZoomOptions = {
        type: 'ZoomOut',
        zoomFactor: 0.2,
        focusPoint: { x: 0.5, y: 0.5 },
    };
    diagramInstance.zoomTo(zoomOptions);
    diagramInstance.dataBind();
  };  
  return (
    <div>
      <button id="zoomIn" onClick={zoomIn}>Zoom In</button>
      <button id="zoomOut" onClick={zoomOut}>Zoom Out</button>
      <DiagramComponent
        id="container"
        ref={(diagram) => (diagramInstance = diagram)}
        width={700}
        height={700}
        nodes={node}
        rulerSettings=
        scrollSettings=
      />
    </div>
  );
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);

For more information on various ways to zoom and pan the diagram, refer to zoomPan with various ways

AutoScroll

The autoscroll feature automatically scrolls the diagram when a node or connector is moved beyond its boundary. This ensures that the element remains visible during operations like dragging, resizing, and selection.

The autoscroll behavior triggers automatically when any of the following actions occur towards the edges of the diagram:

  • Node dragging or resizing
  • Connector control point editing
  • Rubber band selection

The client-side event ScrollChange is triggered when autoscroll occurs, allowing for customizations. Refer scrollChange-event for more information.

Autoscroll behavior can be enabled or disabled using the canAutoScroll property of the diagram.

Autoscroll border

The autoscroll border defines the maximum distance from the mouse pointer to the diagram edge that triggers autoscroll. By default, this distance is set to 15 pixels for all sides (left, right, top, and bottom). You can adjust this using the autoScrollBorder property of the scroll settings.

The following example demonstrates how to configure autoscroll:

import * as React from "react";
import * as ReactDOM from "react-dom";
import { DiagramComponent, ConnectorConstraints, ConnectorEditing, Inject  } from "@syncfusion/ej2-react-diagrams";

let connector = [
    {
      id: 'connetor',
      type: 'Bezier',
      segments: [{ type: 'Bezier', point: { x: 150, y: 100 } }],
      sourcePoint: { x: 100, y: 100 },
      targetPoint: { x: 300, y: 100 },
      annotations: [
        {
          content: 'Adjust control point or end point to autoScroll',
          alignment: 'After',
        },
      ],
      constraints:
        ConnectorConstraints.Default | ConnectorConstraints.DragSegmentThumb,
    },
  ];
let nodes = [{
    id: 'node1',
    width: 100,
    height: 60,
    offsetX: 200,
    offsetY: 300,
    annotations: [
      { content: 'Drag or resize the node to activate autoscroll' },
    ],
  }];
function App() {
    return (<DiagramComponent id="container" width={'100%'} height={'600px'} nodes={nodes} connectors={connector} rulerSettings={{ showRulers: true }}
    scrollSettings={{
        scrollLimit: 'Infinity',
        canAutoScroll: true,
        autoScrollBorder: {
            left: 100,
            right: 100,
            top: 100,
            bottom: 100
        }
    }}>
    <Inject services={[ConnectorEditing]}/>
    </DiagramComponent>);
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);
import * as React from "react";
import * as ReactDOM from "react-dom";
import {
    NodeModel,
    ConnectorModel,
    DiagramComponent,
    ConnectorConstraints,
    ConnectorEditing,
    Inject
} from "@syncfusion/ej2-react-diagrams";
let connector: ConnectorModel[] = [
  {
    id: 'connetor',
    type: 'Bezier',
    segments: [{ type: 'Bezier', point: { x: 150, y: 100 } }],
    sourcePoint: { x: 100, y: 100 },
    targetPoint: { x: 300, y: 100 },
    annotations: [
      {
        content: 'Adjust control point or end point to autoScroll',
        alignment: 'After',
      },
    ],
    constraints:
      ConnectorConstraints.Default | ConnectorConstraints.DragSegmentThumb,
  },
];
let nodes: NodeModel[] = [{
  id: 'node1',
  width: 100,
  height: 60,
  offsetX: 200,
  offsetY: 300,
  annotations: [
    { content: 'Drag or resize the node to activate autoscroll' },
  ],
}];
function App() {
  return (
    <DiagramComponent
      id="container"
      width={'100%'}
      height={'600px'}
      nodes={nodes}
      connectors={connector}
      rulerSettings={{ showRulers: true }}
      // set the autoScrollBorder
      scrollSettings = {
        {
          scrollLimit: 'Infinity',
          canAutoScroll: true,
          autoScrollBorder: {
            left: 100,
            right: 100,
            top: 100,
            bottom: 100
          }
        }
      }>
    <Inject services={[ConnectorEditing]}/>
    </DiagramComponent>
  );
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);

NOTE

To use auto scroll the scrollLimit should be set as ‘Infinity’

Controlling Autoscroll Speed

You can control how often the scrolling needs to be performed automatically in the Diagram component during the auto-scrolling behavior. You can now adjust the frequency, ranging from slow and smooth to quick and rapid, to suit their preferences. To configure, set the value in milliseconds to the autoScrollFrequency property within the scrollSettings class, allowing precise control over how often auto-scrolling occurs.

AutoscrollFrequency GIF

Scroll limit

The scrollLimit allows you to define the scrollable region of the diagram. It includes the following options:

  • Infinity: Allows scrolling in all directions without any restriction.
  • Diagram: Allows scrolling within the diagram region.
  • Limited: Allows scrolling within a specified scrollable area.

The scrollLimit property in scroll settings helps to define these limits.

Scrollable Area

Scrolling beyond a particular rectangular area can be restricted by using the scrollableArea property in scrollSettings. To restrict scrolling beyond a custom region, set the scrollLimit to “limited” and define the desired bounds in scrollableArea property.

The following code example illustrates how to specify the scroll limit and customize the scrollable area.

import * as React from "react";
import * as ReactDOM from "react-dom";
import { Rect, DiagramComponent } from "@syncfusion/ej2-react-diagrams";
let diagramInstance;
let nodes = [{
        id: 'Start',
        width: 140,
        height: 50,
        offsetX: 300,
        offsetY: 50,
        annotations: [{
                id: 'label1',
                content: 'Start'
            }],
        shape: {
            type: 'Flow',
            shape: 'Terminator'
        }
    }];
function App() {
    const scrollableArea = (args) => {
        diagramInstance.scrollSettings.scrollLimit = args.target.value;
        diagramInstance.dataBind();
    };
    return (
    <div>
        <label>Scrollable Area</label>
        <select id="scrollLimit" onChange={scrollableArea}>
        <option value="Limited">Limited</option>
        <option value="Infinity">Infinity</option>
        <option value="Diagram">Diagram</option>
        </select>
        <DiagramComponent id="container" ref={(diagram) => (diagramInstance = diagram)} width={'100%'} height={'600px'} nodes={nodes} rulerSettings={{ showRulers: true }} scrollSettings={{
            canAutoScroll: true,
            //Sets the scroll limit
            scrollLimit: 'Limited',
            //Sets the scrollable Area
            scrollableArea: new Rect(0, 0, 1500, 1500),
        }}/>
    </div>);
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);
import * as React from "react";
import * as ReactDOM from "react-dom";
import {
    NodeModel,
    ConnectorModel,
    Rect,
    DiagramComponent
} from "@syncfusion/ej2-react-diagrams";
let diagramInstance: DiagramComponent;
let nodes: NodeModel[] = [{
    id: 'Start',
    width: 140,
    height: 50,
    offsetX: 300,
    offsetY: 50,
    annotations: [{
        id: 'label1',
        content: 'Start'
    }],
    shape: {
        type: 'Flow',
        shape: 'Terminator'
    }
}];
function App() {
  const scrollableArea = (args: any) => {
    diagramInstance.scrollSettings.scrollLimit = args.target.value;
    diagramInstance.dataBind();
  };
  return (
    <div>
      <label>Scrollable Area</label>
      <select id="scrollLimit" onChange={scrollableArea}>
        <option value="Limited">Limited</option>
        <option value="Infinity">Infinity</option>
        <option value="Diagram">Diagram</option>
      </select>
      <DiagramComponent
        id="container"
        ref={(diagram) => (diagramInstance = diagram)}
        width={'100%'}
        height={'600px'}
        nodes={nodes}
        rulerSettings={{ showRulers: true }}
        scrollSettings={{
          canAutoScroll: true,
          //Sets the scroll limit
          scrollLimit: 'Limited',
          //Sets the scrollable Area
          scrollableArea: new Rect(0, 0, 1500, 1500),
        }}
      />
    </div>
  );
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);

Scroll Padding

The padding property of the scroll settings allows you to extend the scrollable region based on the scroll limit. This property is useful for adding extra space around the diagram content, making it easier to navigate and interact with elements near the edges.

The following code example illustrates how to set scroll padding for the diagram region:

import * as React from "react";
import * as ReactDOM from "react-dom";
import { DiagramComponent } from "@syncfusion/ej2-react-diagrams";
let nodes = [{
        id: 'node',
        width: 100, height: 100,
        offsetX: 350, offsetY: 350,
    }];
function App() {
    return (<DiagramComponent id="container" width={'100%'} height={'600px'} nodes={nodes} rulerSettings={{ showRulers: true }} scrollSettings={{
            //Sets the scroll padding
            padding: { left: 100, top: 100 }
        }}/>);
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);
import * as React from "react";
import * as ReactDOM from "react-dom";
import {
    NodeModel,
    DiagramComponent
} from "@syncfusion/ej2-react-diagrams";
let nodes: NodeModel[] = [{
    id: 'node',
    width: 100, height: 100,
    offsetX: 350, offsetY: 350,
}];
function App() {
  return (
    <DiagramComponent
      id="container"
      width={'100%'}
      height={'600px'}
      nodes={nodes}
      rulerSettings={{ showRulers: true }}
      scrollSettings={{
        //Sets the scroll padding
        padding: { left: 100, top: 100 }
      }}
    />
  );
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);

Reset scroll

The reset method resets the zoom and scroller offsets to their default values.

//Resets the scroll and zoom to default values
diagramInstance.reset();

UpdateViewport

The updateViewPort method is used to update the dimensions of the diagram viewport.

//Updates diagram viewport
diagramInstance.updateViewPort();

Events

Scroll change event

The scrollChange event is triggered whenever the scrollbar is updated. This can occur during actions such as zooming in, zooming out, using the mouse wheel, or panning. The following example shows how to capture the scrollChange event.

import * as React from "react";
import * as ReactDOM from "react-dom";
import { DiagramComponent, DiagramTools } from "@syncfusion/ej2-react-diagrams";
let nodes = [{
        id: 'Start',
        width: 140,
        height: 50,
        offsetX: 300,
        offsetY: 50,
        annotations: [{
            id: 'label1',
            content: 'Rectangle'
        }],
    }];
let tool = DiagramTools.ZoomPan;
function App() {
    const scrollChange= (args) => {
        console.log(args.panState);
        //Handle scrollChange event for custom logic
      };  
    return (<DiagramComponent id="container" width={'100%'} height={'600px'} tool={tool} nodes={nodes} scrollSettings={{
            //Sets the scroll limit
            scrollLimit: 'Infinity',
        }}
        scrollChange={scrollChange} />);
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);
import * as React from "react";
import * as ReactDOM from "react-dom";
import {
    NodeModel,
    DiagramComponent,
    DiagramTools,
    IScrollChangeEventArgs
} from "@syncfusion/ej2-react-diagrams";
let nodes: NodeModel[] = [{
  id: 'Start',
  width: 140,
  height: 50,
  offsetX: 300,
  offsetY: 50,
  annotations: [{
    id: 'label1',
    content: 'Rectangle'
  }],
}];
let tool: DiagramTools = DiagramTools.ZoomPan;
function App() {
  const scrollChange= (args: IScrollChangeEventArgs) => {
    console.log(args.panState);
    //Handle scrollChange event for custom logic
  }; 
  return (
    <DiagramComponent
      id="container"
      width={'100%'}
      height={'600px'}
      tool={tool}
      nodes={nodes}
      scrollSettings={{
        //Sets the scroll limit
        scrollLimit: 'Infinity',
      }}
      scrollChange={scrollChange}
    />
  );
}
const root = ReactDOM.createRoot(document.getElementById('diagram'));
root.render(<App />);