Shopify Draggable

The @shopify/draggable library includes several plugins by default that extend the core dragging functionality. These plugins are available for use to add specific behaviors like announcement for accessibility, focus management, visual mirroring, or scroll handling during drag operations.

Included plugins:

• Announcement: Provides accessibility announcements (e.g., via ARIA live regions) about the drag state.
• Focusable: Manages focus during drag interactions.
• Mirror: Creates a visual mirror/ghost of the element being dragged.
• Scrollable: Handles automatic scrolling when a dragged element is moved near the boundaries of a scrollable container.

Swappable is a specialized extension built on top of Draggable. It enables users to swap elements by dragging one element over another.

Key distinction from Sortable: Unlike a Sortable implementation, Swappable does not maintain a specific order. Instead, any draggable element that is dragged over a target element will be swapped with the source element.

Sortable is a specialized implementation built on top of Draggable designed specifically for reordering elements. It maintains the order of elements internally and provides additional lifecycle events specifically for sorting operations.

Requirement: For Sortable to function correctly, you must ensure that draggable elements are immediate children of their corresponding containers.

All events emitted by a Draggable instance are based on the DraggableEvent interface. This base event is not cancelable and provides access to the draggable instance itself.

Key properties:

• type: Always returns the string 'draggable'.
• draggable: A read-only property that provides the current Draggable instance associated with the event.

The Snappable plugin simulates a "snap" effect by hiding the mirror element and removing the 'source:dragging' class from the source element. It also applies the 'source:placed' class to the source for potential drop animations.

Note: This plugin is not included by default; you must explicitly import and include it in your plugins array when initializing a Draggable or Sortable instance.

import {Draggable, Plugins} from '@shopify/draggable';

const draggable = new Draggable(document.querySelectorAll('ul'), {
  draggable: 'li',
  plugins: [Plugins.Snappable],
});

The SnapEvent is the base interface for all snap-related events emitted by the Snappable plugin. It is not cancelable. It provides context about the drag operation and the target element involved in the snapping process.

interface SnapEvent {
  readonly dragEvent: DragEvent;
  readonly snappable: HTMLElement;
}

The Focusable plugin makes draggable containers and elements focusable by decorating them with tabindex attributes during initialization. It is designed to improve accessibility by allowing keyboard users to interact with draggable items.

Important behavior: The plugin will not override any existing tabindex attributes already present on your elements.

The DragSensor picks up native browser drag events and triggers drag:start, drag:move, and drag:stop events on the source container.

Note: Draggable does not use this sensor by default. It relies on the native Drag and Drop API, which means Draggable does not create a custom mirror element, resulting in less control over the visual drag mirror compared to other sensors.

Important Limitations:

• The distance option is not supported when using this sensor.
• It uses the native Drag and Drop API.

import {Draggable, Sensors} from '@shopify/draggable';

const draggable = new Draggable(containers, {
  sensors: [Sensors.DragSensor],
});

// Remove default mouse sensor to ensure only DragSensor is used
draggable.removeSensor(Sensors.MouseSensor);

The SensorEvent is the base interface for all sensor events emitted by the library. It provides normalized data for both mouse and touch interactions. Note that SensorEvent is not cancelable.

Key properties available on all sensor events:

• originalEvent: The underlying browser Event that triggered the sensor.
• clientX: The current X coordinate of the pointer.
• clientY: The current Y coordinate of the pointer.
• target: The HTMLElement currently under the cursor or touch pointer.
• container: The element that fired the sensor event.
• originalSource: The element that was initially picked up to start the drag.
• pressure: The amount of pressure applied (useful for pressure-sensitive touch devices).

All sortable events emitted by the Sortable class inherit from the SortableEvent base interface. SortableEvent provides access to the original browser DragEvent that triggered the sortable action via the dragEvent property. Note that SortableEvent itself is not cancelable.

// Accessing the underlying browser event from a sortable event
const originalEvent = sortableEvent.dragEvent;