Pragmatic drag and drop: Atlassian's low level toolchain for the browser's native drag and drop

What problem Pragmatic drag and drop solves, and who it is for

The browser already implements drag and drop. The problem is that the built in behaviour is awkward to use correctly: the events are inconsistent across engines, the drag image is hard to control, and making the interaction work for keyboard and screen reader users is a separate project on its own. Pragmatic drag and drop is a low level toolchain that the README describes as enabling "safe and successful usage of the browsers built in drag and drop functionality". It does not replace the native mechanism with a pointer-event reimplementation. It sits on top of it.

The intended audience is a team building drag and drop inside its own product, with its own components and its own design language. The README is explicit that the packages are "unopinionated about visual language or accessibility, and have no dependency on the Atlassian Design System". If you want a drop-in sortable list with a default look, this is the wrong shape of library. If you want the behaviour layer and intend to render everything yourself, it is the right shape.

Atlassian states that the toolchain powers Trello, Jira and Confluence, which is a useful signal about the scale it was built for. It is not a claim you can verify from the repository alone, but it does explain some of the design choices, particularly the emphasis on deferred loading and on keeping the core package small.

The core package and the optional packages: how the toolchain is split

Pragmatic drag and drop is not one library. It is a small core package plus a set of optional packages, and the README frames the split as the central design decision. The core is advertised at roughly 4.7kB and contains the drag and drop behaviour. Everything else, the drop indicator visuals, the hitbox helpers, the assistive technology controls, lives in packages you install only if you need them.

The import path reflects that split. The README gives this example of pulling in the element adapter:

import { draggable } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';

The packages are published under the `@atlaskit` namespace on npm, which is Atlassian's public namespace for everything it ships out of its internal monorepo. The README acknowledges this is a slightly odd home for a general purpose library and says a separate namespace could be explored in the future, with tooling to help people switch over if that happens. For now, `@atlaskit` is where the packages live.

Some optional packages carry dependencies on other things: `emotion` for styling, `react` for view bindings, `@atlaskit/tokens` for Atlassian's design tokens. The README explains that these were separated out precisely so they can be swapped for your own equivalents. That is the trade-off to understand before adopting: the core is genuinely dependency-light, but the moment you reach for the visual or accessibility packages you inherit Atlassian's stack unless you write your own replacements.

Installing Pragmatic drag and drop and wiring a first draggable

The README does not walk through a full setup, but it does give the import path and the namespace, which is enough to install. Packages are published on npm under `@atlaskit`, so installation follows the normal pattern for your package manager. The exact package name depends on which pieces you need; the core package and the element adapter are the starting point for a plain DOM drag.

npm install @atlaskit/pragmatic-drag-and-drop

After installing, the first real step is to make an element draggable. The README's example imports `draggable` from `@atlaskit/pragmatic-drag-and-drop/element/adapter`. In practice you give that function a DOM element and it attaches the native drag behaviour to it, which means the element needs a `draggable` attribute in your markup for the browser to start a drag at all. The adapter handles the wiring; you still own the element.

Because the toolchain is headless, nothing appears on screen after this step. There is no default drag preview, no default drop indicator, no default styling. That surprises people coming from component libraries. The README's optional visual outputs, such as the drop indicator, exist precisely because the core deliberately ships none of this. Expect your first working drag to be invisible until you add your own visual feedback or install the optional output packages.

If you are working in React, Svelte, Vue or Angular, the README states the toolchain works with any view layer. The framework-specific packages are optional conveniences rather than requirements, which is why the core import above is framework neutral.

Accessibility is a toolchain, not a default

This is the part that most drag and drop libraries handle badly, and Pragmatic drag and drop takes a deliberate position: it gives you the pieces rather than the finished behaviour. The README notes that "not all users can achieve pointer based drag and drop experiences" and provides optional assistive technology controls so you can wire up keyboard-friendly flows for any experience.

Those controls are built on the Atlassian Design System. The README says that if you do not want to use that system, you can follow the guidelines and substitute your own components, or take a different approach entirely. Read that carefully. The accessibility packages are not a switch you flip. They are a starting point that assumes Atlassian's component library, and adapting them to another design system is work you take on.

For a team shipping an internal tool with a small user base, that may be fine. For a product with accessibility requirements and a non-Atlassian component library, budget for the substitution. The core being headless means nothing stops you from building an accessible flow your own way, but the library will not do it for you, and the README is honest about that rather than implying otherwise.

Where Pragmatic drag and drop is the wrong tool

The clearest limitation is the one the README states outright: this repository is "one way mirror from our internal monorepo". Code flows out, not in. The README says the intention is to make the code public but not to accept code contributions at this stage, though issues and suggestions are welcome. If your team expects to send patches upstream, or if you depend on a library where you can fix a bug yourself and get it merged, that expectation does not hold here.

There is a second, subtler cost. The mirror is synced once a day, while packages are published to npm immediately as versions merge internally. The README states that code can be released to npm up to 24 hours before it appears in the mirror repository. So the source you read on the default branch may lag the artifact you install. When you are debugging something odd in a newly published version, check whether the mirror has caught up before assuming the code you are reading is the code you are running.

A third boundary: the library is low level by design. If your requirement is a sortable list, a kanban board or a file drop zone with a known look, you will write a substantial amount of code that a higher level library would have given you. The README's own framing, "create any experience you want", is a statement of flexibility, and flexibility of that kind is paid for in implementation time. Teams with a small drag and drop surface area and a tight deadline should weigh that honestly.

How it differs from dnd-kit and similar component-oriented libraries

The natural comparison is dnd-kit, which people search for alongside this project. The approaches differ at the foundation. dnd-kit implements drag and drop with pointer events and its own sensor abstraction, which gives it consistent behaviour across input types and lets it support touch and pointer interactions on its own terms. Pragmatic drag and drop instead builds on the browser's native drag and drop API, and the README's stated goal is to make that native functionality usable safely rather than to replace it.

That difference shows up in what you get out of the box. dnd-kit ships sortable presets and a set of hooks that assume a component-tree model, so a basic sortable list is a short amount of code. Pragmatic drag and drop ships behaviour plus optional visual outputs, and the README lists "virtualization support" and "deferred compatible" as capabilities, which points at large, performance-sensitive surfaces rather than small widgets. The README also claims full feature support in Firefox, Safari, Chrome, iOS and Android, which is the payoff for staying on the native API.

The practical question is not which library is better but which constraint binds you. If you need a sortable list this week, dnd-kit's presets will get you there faster. If you need drag and drop inside a virtualized tree or a canvas-like surface where you control every pixel, the native-API approach and the headless core are the reason to pick this one. Note that the README does not document a migration path between the two, so switching later means rewriting your interaction layer.

Licence, maintenance and the cost of upgrading

The repository's package.json declares `"license": "Apache-2.0"` for the workspace, though the repository metadata itself reports the licence as NOASSERTION, meaning GitHub could not classify the LICENSE file automatically. Apache-2.0 is a permissive licence that allows commercial use and modification, and it includes a patent grant. This is a description of what the files say, not legal advice; if the licence matters to your organisation, read the LICENSE file at the repository root rather than trusting a classifier.

On maintenance, the last push to the default branch was on 2026-09-19, two days before this writing, and the repository is not archived. That is a current signal, but the mirror model changes what it means. Activity in this repository reflects a sync from an internal monorepo, not necessarily the pace of development itself, and the README confirms the sync runs once a day. The npm packages are the actual release channel.

Upgrade cost is where the package split helps and hurts. Because the core is small and the optional packages are separate, you can upgrade the core without pulling in visual or accessibility changes you do not use. But the optional packages that depend on `emotion`, `react` or `@atlaskit/tokens` inherit those dependencies' upgrade cycles too. If you have replaced them with your own implementations, you have also taken on maintaining those replacements. Budget for that before you decide to fork the visual layer.

Editorial conclusion

Adopt Pragmatic drag and drop if you are building drag and drop into a product where you control the view layer and the visual language, and you are willing to wire up accessibility yourself. Do not adopt it if you want a ready made sortable list component, because the project deliberately ships behaviour rather than a finished widget. Before you commit, verify that the packages you need are published under the @atlaskit namespace on npm, and check the mirror repository's daily sync delay against the version you actually install.

Frequently asked questions

Official sources

1. atlassian/pragmatic-drag-and-drop on GitHub
2. Issues
3. Project website
4. README