useDraggableAutoScroll

A React hook that adds auto-scroll functionality to a Draggable instance using the auto-scroll plugin.

Usage

import { useRef, useMemo, useCallback } from 'react';
import { usePointerSensor, useDraggable, useDraggableAutoScroll } from 'dragdoll-react';

function DraggableBox() {
  const elementRef = useRef<HTMLDivElement | null>(null);
  const [pointerSensor, setPointerSensorElementRef] = usePointerSensor();
  const draggableSettings = useMemo(
    () => ({
      elements: () => (elementRef.current ? [elementRef.current] : []),
    }),
    [],
  );
  const autoScrollSettings = useMemo(
    () => ({
      targets: [{ element: window, priority: 0 }],
      speed: 500,
    }),
    [],
  );

  // You simply wrap the `useDraggable` hook with the `useDraggableAutoScroll`
  // hook, as easy as that. This way the returned draggable instance will have
  // the correct types (extended by the autoscroll plugin).
  const draggable = useDraggableAutoScroll(
    useDraggable([pointerSensor], draggableSettings),
    autoScrollSettings,
  );

  const setRefs = useCallback(
    (node: HTMLDivElement | null) => {
      elementRef.current = node;
      setPointerSensorElementRef(node);
    },
    [setPointerSensorElementRef],
  );

  return (
    <div
      ref={setRefs}
      style={{ position: 'relative', width: '100px', height: '100px', backgroundColor: 'red' }}
    >
      Drag me
    </div>
  );
}

Signature

function useDraggableAutoScroll<S extends Sensor = Sensor, P extends DraggablePluginMap = {}>(
  draggable: Draggable<S, P> | null,
  settings?: UseDraggableAutoScrollSettings<S>,
): ReturnType<ReturnType<typeof autoScrollPlugin<S, P>>> | null;

Parameters

draggable

type draggable = Draggable<S, P> | null;

The Draggable instance to add auto-scroll functionality to. Can be null if not yet initialized.

• Required.

settings

type settings = UseDraggableAutoScrollSettings<S>;

Configuration options for auto-scrolling. See the auto-scroll plugin settings for all the available options.

WARNING

You MUST memoize the settings object (e.g. with useMemo) to prevent unnecessary re-evaluations and performance issues.

As per React's declarative nature, these settings are always merged with the default settings and then provided to the DraggableAutoScroll instance. This way there will be no cumulative effect of settings changes over time meaning that the old settings will be completely overridden by the new settings.

• Optional.
• Default is undefined.

Return Value

type returnValue = ReturnType<ReturnType<typeof autoScrollPlugin<S, P>>> | null;

Returns the Draggable instance with the auto-scroll plugin attached (which also extends the Draggable instance's types).

Returns null if the draggable parameter is null.

Types

UseDraggableAutoScrollSettings

// Import
import type { UseDraggableAutoScrollSettings } from 'dragdoll-react';

// Type
type UseDraggableAutoScrollSettings<S extends Sensor = Sensor> = DraggableAutoScrollOptions<S>;