AutoScroller - Dnd Kit

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:

<CodeGroup> ```ts Vanilla import {DragDropManager, AutoScroller} from '@dnd-kit/dom';

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


```tsx React
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>
  );
}

vue

<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>

svelte

<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>

tsx

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

</CodeGroup>

Options

<ParamField path="acceleration" type="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. </ParamField> <ParamField path="threshold" type="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. </ParamField>

Disabling

To disable auto-scrolling, omit the AutoScroller from the plugins array:

<CodeGroup> ```ts Vanilla import {DragDropManager, AutoScroller} from '@dnd-kit/dom';

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


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

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

vue

<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>

svelte

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

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

tsx

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

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

</CodeGroup>

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

<CodeGroup> ```ts Vanilla 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();


```tsx React
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>
  );
}

vue

<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>

svelte

<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>

tsx

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

</CodeGroup>