pragmatic-drag-and-drop README

The project's README from github.com/atlassian/pragmatic-drag-and-drop. As one markdown file: README.md.

Fast drag and drop for any experience on any tech stack

📖 Documentation | 🤹 Examples | 🎥 How it works

Show case of some examples


About

Pragmatic drag and drop is a low level drag and drop toolchain that enables safe and successful usage of the browsers built in drag and drop functionality. Pragmatic drag and drop can be used with any view layer (react, svelte, vue, angular and so on). Pragmatic drag and drop is powering some of the biggest products on the web, including Trello, Jira and Confluence.

Capabilities

Pragmatic drag and drop consists of a few high level pieces:

  1. Low level drag and drop behavior

Pragmatic drag and drop contains a core package, and a number of optional packages, that provide you the pieces to create any drag and drop experience.

These pieces are unopinionated about visual language or accessibility, and have no dependency on the Atlassian Design System.

  • Tiny: ~`4.7kB` core
  • Incremental: Only use the pieces that you need
  • Headless: Full rendering and style control
  • Framework agnostic: Works with any frontend framework
  • Deferred compatible: Delay the loading the core packages and optional packages in order to further improve page load speeds
  • Flexible: create any experience you want, make any changes you want during a drag operation.
  • Works everywhere: Full feature support in Firefox, Safari, and Chrome, iOS and Android
  • Virtualization support: create any virtual experience you want!
  1. Optional visual outputs

We have created optional visual outputs (eg our drop indicator) to make it super fast for us to build consistent Atlassian user experiences. Non Atlassian consumers are welcome to use these outputs, create their own that copy the visual styling, or go a totally different direction.

  1. Optional assistive technology controls

Not all users can achieve pointer based drag and drop experiences. In order to achieve fantastic experiences for assistive technology users, we provide a toolchain to allow you to quickly wire up performant assistive technology friendly flows for any experience.

The optional assistive controls we provide are based on the Atlassian Design System. If you do not want to use the Atlassian Design System, you can use our guidelines and substitute our components with your own components, or you can go about accessibility in a different way if you choose.

What is this repository?

This repository is currently one way mirror from our internal monorepo that contains all the code for Pragmatic drag and drop.

Diagram of how the mirror works

The intention of this repository is to make public our code, but not to accept code contributions (at this stage). In the future we could explore setting up a two way mirror so that contributions to this repo can also make their way back to our monorepo. You are still welcome to raise issues or suggestions on this repository!

All documentation and npm packages are public and available for use by everyone.

Can I use this with my own Design System?

Yep! Pragmatic drag and drop as a small core package, and then a range of optional packages. Some of the optional packages have dependencies on styling solutions (eg emotion), view libraries (eg react) or on some additional Atlassian outputs (eg @atlaskit/tokens). We have separated out optional packages that have other dependencies so they can be easily swapped with your own pieces that use your own tech stack and visual outputs.

Can I use my own design language?

Yep! We have created some design guidelines which embody how we want to achieve drag and drop in our products, and some of those decisions are embodied in some optional packages. However, you are free to use whatever design language you like, including ours!

What is @atlaskit?

The Pragmatic drag and drop packages are published under the @atlaskit namespace on npm

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

@atlaskit is the npm namespace that we publish all of our public packages on from inside our internal monorepo. We could look at creating a separate namespace in the future just for Pragmatic drag and drop. If we do that, we'll release some tooling to help folks automatically switch over.

npm release and repo sync timing

This mirror repository is currently being synced with our internal repository once a day. We publish packages to npm immediately as we merge new versions into the internal repository. This means that code can be released onto npm up to 24 hours before it is available in this mirror repository.

Credits

Made with love by:

Pragmatic drag and drop stands on the shoulders of giants, including the folks who created the drag and drop specifications, implemented drag and drop in browsers, and the many drag and drop libraries that came before this.

pragmatic-drag-and-drop (atlassian/pragmatic-drag-and-drop)

Searching Database…

12.8K ·GitHub
Pragmatic-drag-and-drop
What is this?Pragmatic drag and drop is a low-level drag and drop toolchain built on top of the browser's native drag and drop API, used to power drag and drop in Trello, Jira, and Confluence.
Is it a framework or a library?It is a headless, unopinionated library: a tiny core package plus optional packages for visuals and accessibility, with no required UI framework.
How do I add it to a project?Install the packages you need from the @atlaskit npm namespace and wire up only the pieces required for your drag and drop experience.
Does it tie me to the Atlassian Design System or a specific frontend framework?No, it can be used with any view layer (React, Svelte, Vue, Angular, etc.); only some optional packages depend on things like emotion or Atlassian tokens, and those can be swapped out.
Which browsers and platforms does it actually support?It aims for full feature support in Firefox, Safari, and Chrome, as well as iOS and Android.
Does it come with built-in drag indicators and visuals?Yes, it includes optional visual outputs like a drop indicator that Atlassian uses for consistent UX, which others can reuse, copy, or replace entirely.
Does it support users who can't use pointer-based dragging?Yes, it provides optional assistive technology controls based on the Atlassian Design System to create accessible drag and drop flows for keyboard and screen reader users.
Can I use npm published packages even though the GitHub mirror lags behind?Yes, npm packages are published immediately on internal merges, while this mirrored repo syncs once a day, so npm can be up to 24 hours ahead of what you see here.
Does it support virtualized lists?Yes, the toolchain explicitly supports building virtualized drag and drop experiences.
What are similar projects?react-beautiful-dnd, dnd-kit, Vue.Draggable, loadersz-core, tiptap, tabler-icons, fullcalendar, dropzone
Which topics is it in?sortable, headless, drag-and-drop, svelte, angular, accessibility, javascript-library, vue, ui-components, performance, react, npm
Creator
atlassian
Size
11.5 MB
Stars
12.8K
Updated
CommitOct 16
Age
2y
Commits · 90 Days