Drag previews

type State =
    | {
            type: 'idle';
      }
    | {
            type: 'preview';
            container: HTMLElement;
      };

function Item() {
    const [state, setState] = useState<State>({ type: 'idle' });
    const ref = useRef<HTMLDivElement | null>(null);

    useEffect(() => {
        invariant(ref.current);

        return draggable({
            element: ref.current,
            onGenerateDragPreview({ nativeSetDragImage }) {
                setCustomNativeDragPreview({
                    render({ container }) {
                        // Cause a `react` re-render to create your portal synchronously
                        setState({ type: 'preview', container });
                        // In our cleanup function: cause a `react` re-render to create remove your portal
                        // Note: you can also remove the portal in `onDragStart`,
                        // which is when the cleanup function is called
                        return () => setState({ type: 'idle' });
                    },
                    nativeSetDragImage,
                });
            },
        });
    }, []);

    return (
        <>
            <div ref={ref}>Drag Me</div>
            {state.type === 'preview' ? ReactDOM.createPortal(<Preview />, state.container) : null}
        </>
    );
}

import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';

draggable({
    element: myElement,
    onGenerateDragPreview: ({ nativeSetDragImage }) => {
        setCustomNativeDragPreview({
            render({ container }) {
                ReactDOM.render(<Preview item={item} />, container);
                return function cleanup() {
                    ReactDOM.unmountComponentAtNode(container);
                };
            },
            nativeSetDragImage,
        });
    },
});

import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';

draggable({
    element: myElement,
    onGenerateDragPreview: ({ nativeSetDragImage }) => {
        setCustomNativeDragPreview({
            render({ container }) {
                // Create our preview element
                const preview = document.createElement('div');

                // Populate and style the preview element however you like
                preview.textContent = 'My Preview';
                Object.assign(preview.style, {
                    padding: '20px',
                    backgroundColor: 'lightpink',
                });

                // put the "preview" element into the container element
                container.appendChild(preview);
            },
            nativeSetDragImage,
        });
    },
});

const rect = container.getBoundingClientRect()

• {x: 0, y: 0} → top left of the container will be under the users pointer (default)
• {x: rect.width, y: 0} top right of the container will be under the users pointer
• {x: rect.width, y: rect.height} bottom right of the container will be under the users pointer
• {x: 0, y: rect.height} bottom left of the container will be under the users pointer

type GetOffsetFn = (args: { container: HTMLElement }) => {
    x: number;
    y: number;
};

• GetOffsetFn needs to return x and y as numbers as that is what the platform requires
• You cannot use negative values (not supported by browsers). If you want to push the drag preview away from the users pointer, use pointerOutsideOfPreview (see below)
• The max offset value for an axis is the border-box. Values greater than the border-box get trimmed to be the border-box value
• getOffset is called in the next microtask, (opens new window) after setCustomNativeDragPreview:render. This helps ensure that the drag preview element has finished rendering into the container before getOffset is called. Some frameworks like react@18 won't render the element to be used for the drag preview into the container until the next microtask.

import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';

draggable({
    element: myElement,
    onGenerateDragPreview: ({ nativeSetDragImage }) => {
        setCustomNativeDragPreview({
            // place the (near) top middle of the `container` under the users pointer
            getOffset: () => {
                const rect = container.getBoundingClientRect();
                return { x: rect.width / 2, y: 16 };
            },
            render({ container }) {
                ReactDOM.render(<Preview item={item} />, container);
                return function cleanup() {
                    ReactDOM.unmountComponentAtNode(container);
                };
            },
            nativeSetDragImage,
        });
    },
});

1. centerUnderPointer: centers the custom native drag preview under the users cursor

import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
import { centerUnderPointer } from '@atlaskit/pragmatic-drag-and-drop/element/center-under-pointer';

draggable({
    element: myElement,
    onGenerateDragPreview: ({ nativeSetDragImage }) => {
        setCustomNativeDragPreview({
            getOffset: centerUnderPointer,
            render({ container }) {
                /* ... */
            },
            nativeSetDragImage,
        });
    },
});

2. pointerOutsideOfPreview: a cross browser mechanism to push the drag preview in front of the users pointer.

import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
import { pointerOutsideOfPreview } from '@atlaskit/pragmatic-drag-and-drop/element/pointer-outside-of-preview';

draggable({
    element: myElement,
    onGenerateDragPreview: ({ nativeSetDragImage }) => {
        setCustomNativeDragPreview({
            // `x` and `y` can be any CSS value
            getOffset: pointerOutsideOfPreview({
                x: '8px',
                y: 'calc(var(--grid) * 2)',
            }),
            render({ container }) {
                /* ... */
            },
            nativeSetDragImage,
        });
    },
});

onGenerateDragPreview({ nativeSetDragImage, source, location }) {
    setCustomNativeDragPreview({
        nativeSetDragImage,
        getOffset: pointerOutsideOfPreview({
            x: token('space.200'),
            y: token('space.100'),
        }),
        render({ container }) {
            // Forcing the direction for the container.
            container.dir = 'ltr';

            // By default, the `dir` inherited on `container` (which is a child of `body`) will be used.
        },
    });
},

3. preserveOffsetOnSource: applies the initial cursor offset to the custom native drag preview for a seamless experience

import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
import { preserveOffsetOnSource } from '@atlaskit/pragmatic-drag-and-drop/element/preserve-offset-on-source';

draggable({
    element: myElement,
    onGenerateDragPreview: ({ nativeSetDragImage, location, source }) => {
        setCustomNativeDragPreview({
            getOffset: preserveOffsetOnSource({
                element: source.element,
                input: location.current.input,
            }),
            render({ container }) {
                /* ... */
            },
            nativeSetDragImage,
        });
    },
});

• This helper works best when the rendered preview has the same dimensions as the dragged element
• On Android the center of the drag preview is always under the users pointer (platform limitation)
• On iOS and iPadOS, the drag preview location will initially match the source, but during the drag the native preview will perform an animated slide so that it is centered on the users pointer. The centering of the drag preview during the drag on the users pointer is iOS and iPad platform behaviour.

const isSafari: boolean =
    navigator.userAgent.includes('AppleWebKit') && !navigator.userAgent.includes('Chrome');

const transformStyles = css({
    transform: 'scale(4deg)',
});

function Preview() {
    return <div css={isSafari ? transformStyles : undefined}>Drag preview</div>;
}

1. in onGenerateDragPreview make whatever visual changes you want to the draggable element and those changes will be captured in the drag preview

2. in onDragStart:

   2a. revert changes of step 1. The user will never see the draggable element with the styles applied in onGenerateDragPreview due to paint timings

   2b. apply visual changes to the draggable element to make it clear to the user what element is being dragged

3. in onDrop remove any visual changes you applied to the draggable element during the drag

More information about how this technique works 🧑‍🔬, (opens new window)

• Your draggable needs to be completely visible and unobfiscated at the start of the drag. This can involve insuring that your draggable is not cut off by scroll (see scrollJustEnoughIntoView), and has no layers currently on top of the draggable (for example, you might need to close some popups)
• The users pointer still needs to be over the draggable after the changes you make to the draggable element in onGenerateDragPreview. Generally this means that you should not be changing the dimensions of the draggable element.
• Avoid CSS transform on your draggable. In Safari, CSS transforms that impact a draggable can mess up native drag previews.
  • Bug 1, (opens new window) when a transform impacts a draggablebefore a drag starts:
  • Bug 2, (opens new window) when CSS transform is applied to a draggable element in onGenerateDragPreview

1. disable the native drag preview

import { disableNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/disable-native-drag-preview';

draggable({
    element: myElement,
    onGenerateDragPreview({ nativeSetDragPreview }) {
        disableNativeDragPreview({ nativeSetDragPreview });
    },
});

This technique renders a 1x1 transparent image as the native drag preview. There are a few alternative techniques for hiding the drag preview, but this technique yielded the best results across many browsers and devices.

2. render your own element in onDragStart (ideally in a portal), and under the user's pointer (you can use location.initial.input to get the users initial position)
3. move the new element around in response to onDrag events (use location.current.input to get the users current pointer position)
4. remove the new element in onDrop

import { disableNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/disable-native-drag-preview';

draggable({
    element: myElement,
    onGenerateDragPreview({ nativeSetDragPreview }) {
        disableNativeDragPreview({ nativeSetDragPreview });
    },
});

import { scrollJustEnoughIntoView } from '@atlaskit/pragmatic-drag-and-drop/element/scroll-just-enough-into-view';

draggable({
    element: myElement,
    onGenerateDragPreview({ source }) {
        scrollJustEnoughIntoView({ element: source.element });
    },
});