Skip to main content

​
Overview

The AutoScroller plugin automatically scrolls scrollable containers when the pointer approaches their edges during a drag operation. It works in conjunction with the internal Scroller plugin that detects scrollable ancestors and computes scroll intent. This plugin is included by default when creating a new DragDropManager.

​
Behavior

When a drag operation is in progress and the pointer is near the edge of a scrollable container, the AutoScroller will:
  1. Detect the nearest scrollable ancestor of the element under the pointer.
  2. Compute the scroll direction and speed based on the pointer’s proximity to the edge.
  3. Continuously scroll the container at the computed speed until the pointer moves away from the edge or the container can no longer scroll in that direction.
The scroll speed increases as the pointer gets closer to the edge of the container.

​
Configuration

Use AutoScroller.configure() to customize the scroll speed and activation zone: 
import {DragDropManager, AutoScroller} from '@dnd-kit/dom';

const manager = new DragDropManager({
  plugins: (defaults) => [
    ...defaults,
    AutoScroller.configure({
      acceleration: 15,
      threshold: { x: 0, y: 0.3 },
    }),
  ],
});

​
Options

​
acceleration
number
default:"25"
Base scroll speed multiplier. The scroll speed scales linearly as the pointer approaches the edge of a scrollable container — higher values scroll faster.
​
threshold
number | { x: number; y: number }
default:"{ x: 0.2, y: 0.2 }"
Percentage of container dimensions that defines the scroll activation zone. For example, 0.2 means scrolling activates when the pointer enters the outer 20% of a scrollable container.A single number applies to both axes. Use { x, y } for per-axis control. Setting an axis to 0 disables auto-scrolling on that axis.

​
Disabling

To disable auto-scrolling, omit the AutoScroller from the plugins array: 
import {DragDropManager, AutoScroller} from '@dnd-kit/dom';

const manager = new DragDropManager({
  plugins: (defaults) => defaults.filter((plugin) => plugin !== AutoScroller),
});
To dynamically disable auto-scrolling at runtime, access the plugin instance from the manager registry and call its disable() method: 
import {DragDropManager, AutoScroller} from '@dnd-kit/dom';

const manager = new DragDropManager();
const autoScroller = manager.registry.plugins.get(AutoScroller);

// Disable auto-scrolling
autoScroller.disable();

// Re-enable auto-scrolling
autoScroller.enable();