Auto Scroller Plugin

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:

Detect the nearest scrollable ancestor of the element under the pointer.
Compute the scroll direction and speed based on the pointer’s proximity to the edge.
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:

TypeScriptReactVueSvelteSolid

import {DragDropManager, AutoScroller} from '@dnd-kit/dom';

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

import {DragDropProvider} from '@dnd-kit/react';
import {AutoScroller} from '@dnd-kit/dom';

function App() {
  return (
    <DragDropProvider
      plugins={(defaults) => [
        ...defaults,
        AutoScroller.configure({
          acceleration: 15,
          threshold: { x: 0, y: 0.3 },
        }),
      ]}
    >
      {/* ... */}
    </DragDropProvider>
  );
}

<script setup>
import {DragDropProvider} from '@dnd-kit/vue';
import {AutoScroller} from '@dnd-kit/dom';
</script>

<template>
  <DragDropProvider
    :plugins="(defaults) => [...defaults, AutoScroller.configure({ acceleration: 15, threshold: { x: 0, y: 0.3 } })]"
  >
    <!-- ... -->
  </DragDropProvider>
</template>

<script>
  import {DragDropProvider} from '@dnd-kit/svelte';
  import {AutoScroller} from '@dnd-kit/dom';
</script>

<DragDropProvider
  plugins={(defaults) => [...defaults, AutoScroller.configure({ acceleration: 15, threshold: { x: 0, y: 0.3 } })]}
>
  <!-- ... -->
</DragDropProvider>

import {DragDropProvider} from '@dnd-kit/solid';
import {AutoScroller} from '@dnd-kit/dom';

function App() {
  return (
    <DragDropProvider
      plugins={(defaults) => [
        ...defaults,
        AutoScroller.configure({
          acceleration: 15,
          threshold: { x: 0, y: 0.3 },
        }),
      ]}
    >
      {/* ... */}
    </DragDropProvider>
  );
}

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:

TypeScriptReactVueSvelteSolid

import {DragDropManager, AutoScroller} from '@dnd-kit/dom';

const manager = new DragDropManager({
  plugins: (defaults) => defaults.filter((plugin) => plugin !== AutoScroller),
});

import {DragDropProvider} from '@dnd-kit/react';
import {AutoScroller} from '@dnd-kit/dom';

function App() {
  return (
    <DragDropProvider
      plugins={(defaults) => defaults.filter((plugin) => plugin !== AutoScroller)}
    >
      {/* ... */}
    </DragDropProvider>
  );
}

<script setup>
import {DragDropProvider} from '@dnd-kit/vue';
import {AutoScroller} from '@dnd-kit/dom';
</script>

<template>
  <DragDropProvider
    :plugins="(defaults) => defaults.filter((plugin) => plugin !== AutoScroller)"
  >
    <!-- ... -->
  </DragDropProvider>
</template>

<script>
  import {DragDropProvider} from '@dnd-kit/svelte';
  import {AutoScroller} from '@dnd-kit/dom';
</script>

<DragDropProvider
  plugins={(defaults) => defaults.filter((plugin) => plugin !== AutoScroller)}
>
  <!-- ... -->
</DragDropProvider>

import {DragDropProvider} from '@dnd-kit/solid';
import {AutoScroller} from '@dnd-kit/dom';

function App() {
  return (
    <DragDropProvider
      plugins={(defaults) => defaults.filter((plugin) => plugin !== AutoScroller)}
    >
      {/* ... */}
    </DragDropProvider>
  );
}

To dynamically disable auto-scrolling at runtime, access the plugin instance from the manager registry and call its disable() method:

TypeScriptReactVueSvelteSolid

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();

import {useDragDropManager} from '@dnd-kit/react';
import {AutoScroller} from '@dnd-kit/dom';

function AutoScrollToggle() {
  const manager = useDragDropManager();
  const autoScroller = manager.registry.plugins.get(AutoScroller);

  return (
    <button onClick={() => {
      autoScroller.disabled
        ? autoScroller.enable()
        : autoScroller.disable();
    }}>
      Toggle auto-scroll
    </button>
  );
}

<script setup>
import {useDragDropManager} from '@dnd-kit/vue';
import {AutoScroller} from '@dnd-kit/dom';

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

function toggle() {
  autoScroller.disabled
    ? autoScroller.enable()
    : autoScroller.disable();
}
</script>

<template>
  <button @click="toggle">Toggle auto-scroll</button>
</template>

<script>
  import {getDragDropManager} from '@dnd-kit/svelte';
  import {AutoScroller} from '@dnd-kit/dom';

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

  function toggle() {
    autoScroller.disabled
      ? autoScroller.enable()
      : autoScroller.disable();
  }
</script>

<button onclick={toggle}>Toggle auto-scroll</button>

import {useDragDropManager} from '@dnd-kit/solid';
import {AutoScroller} from '@dnd-kit/dom';

function AutoScrollToggle() {
  const manager = useDragDropManager();
  const autoScroller = manager.registry.plugins.get(AutoScroller);

  return (
    <button onClick={() => {
      autoScroller.disabled
        ? autoScroller.enable()
        : autoScroller.disable();
    }}>
      Toggle auto-scroll
    </button>
  );
}