@hello-pangea/dnd
Version:
Beautiful and accessible drag and drop for lists with React
173 lines (126 loc) โข 11.5 kB
Markdown
<p align="center">
<img src="https://user-images.githubusercontent.com/2182637/53611918-54c1ff80-3c24-11e9-9917-66ac3cef513d.png" alt="react beautiful dnd logo" />
</p>
<h1 align="center">@hello-pangea/dnd</h1>
<div align="center">
**Beautiful** and **accessible** drag and drop for lists with [`React`](https://facebook.github.io/react/)
[](https://circleci.com/gh/hello-pangea/dnd/tree/main)
[](https://www.npmjs.com/package/@hello-pangea/dnd)
[](https://discord.gg/zKhPpmvCEv)
[](https://conventionalcommits.org)
[](http://commitizen.github.io/cz-cli/)
[Play with this example if you want!](https://dnd.hellopangea.com/?path=/story/examples-board--simple)
</div>
## Core characteristics
- Beautiful and [natural movement](/docs/about/animations.md) of items ๐
- [Accessible](/docs/about/accessibility.md): powerful keyboard and screen reader support โฟ๏ธ
- [Extremely performant](/docs/support/media.md) ๐
- Clean and powerful api which is simple to get started with
- Plays extremely well with standard browser interactions
- [Unopinionated styling](/docs/guides/preset-styles.md)
- No creation of additional wrapper dom nodes - flexbox and focus management friendly!
## Get started ๐ฉโ๐ซ
Alex Reardon has created [a free course on `egghead.io` ๐ฅ](https://egghead.io/courses/beautiful-and-accessible-drag-and-drop-with-react-beautiful-dnd) (using [react-beautiful-dnd](https://github.com/atlassian/react-beautiful-dnd)) to help you get started with `@hello-pangea/dnd` as quickly as possible.
[](https://egghead.io/courses/beautiful-and-accessible-drag-and-drop-with-react-beautiful-dnd)
## Currently supported feature set โ
- Vertical lists โ
- Horizontal lists โ
- Movement between lists (โค โ โค)
- [Virtual list support ๐พ](/docs/patterns/virtual-lists.md) - unlocking 10,000 items @ 60fps
- [Combining items](/docs/guides/combining.md)
- Mouse ๐ญ, keyboard ๐นโฟ๏ธ and touch ๐๐ฑ (mobile, tablet and so on) support
- [Multi drag support](/docs/patterns/multi-drag.md)
- Incredible screen reader support โฟ๏ธ - we provide an amazing experience for english screen readers out of the box ๐ฆ. We also provide complete customisation control and internationalisation support for those who need it ๐
- [Conditional dragging](/docs/api/draggable.md#optional-props) and [conditional dropping](/docs/api/droppable.md#conditionally-dropping)
- Multiple independent lists on the one page
- Flexible item sizes - the draggable items can have different heights (vertical lists) or widths (horizontal lists)
- [Add and remove items during a drag](/docs/guides/changes-while-dragging.md)
- Compatible with semantic `<table>` reordering - [table pattern](/docs/patterns/tables.md)
- [Auto scrolling](/docs/guides/auto-scrolling.md) - automatically scroll containers and the window as required during a drag (even with keyboard ๐ฅ)
- Custom drag handles - you can drag a whole item by just a part of it
- Able to move the dragging item to another element while dragging (clone, portal) - [Reparenting your `<Draggable />`](/docs/guides/reparenting.md)
- [Create scripted drag and drop experiences ๐ฎ](/docs/sensors/sensor-api.md)
- Allows extensions to support for [any input type you like ๐น](/docs/sensors/sensor-api.md)
- ๐ฒ Tree support through the [`@atlaskit/tree`](https://atlaskit.atlassian.com/packages/confluence/tree) package
- A `<Droppable />` list can be a scroll container (without a scrollable parent) or be the child of a scroll container (that also does not have a scrollable parent)
- Independent nested lists - a list can be a child of another list, but you cannot drag items from the parent list into a child list
- Server side rendering (SSR) compatible - see [resetServerContext()](/docs/api/reset-server-context.md)
- Plays well with [nested interactive elements](/docs/api/draggable.md#interactive-child-elements-within-a-draggable-) by default
## Motivation ๐ค
`@hello-pangea/dnd` exists to create beautiful drag and drop for lists that anyone can use - even people who cannot see. For a good overview of the history and motivations of the project you can take a look at these external resources:
- ๐ [Rethinking drag and drop](https://medium.com/@alexandereardon/rethinking-drag-and-drop-d9f5770b4e6b)
- ๐ง [React podcast: fast, accessible and beautiful drag and drop](https://reactpodcast.simplecast.fm/17)
## Not for everyone โ๏ธ
There are a lot of libraries out there that allow for drag and drop interactions within React. Most notable of these is the amazing [`react-dnd`](https://github.com/react-dnd/react-dnd). It does an incredible job at providing a great set of drag and drop primitives which work especially well with the [wildly inconsistent](https://www.quirksmode.org/blog/archives/2009/09/the_html5_drag.html) html5 drag and drop feature. `@hello-pangea/dnd` is a higher level abstraction specifically built for lists (vertical, horizontal, movement between lists, nested lists and so on). Within that subset of functionality `@hello-pangea/dnd` offers a powerful, natural and beautiful drag and drop experience. However, it does not provide the breadth of functionality offered by `react-dnd`. One shortcoming is that grid layouts are not supported (yet). So `@hello-pangea/dnd` might not be for you depending on what your use case is.
## Documentation ๐
### About ๐
- [Installation](/docs/about/installation.md)
- [Examples and samples](/docs/about/examples.md)
- [Get started](https://egghead.io/courses/beautiful-and-accessible-drag-and-drop-with-react-beautiful-dnd) (This is using [react-beautiful-dnd](https://github.com/atlassian/react-beautiful-dnd))
- [Design principles](/docs/about/design-principles.md)
- [Animations](/docs/about/animations.md)
- [Accessibility](/docs/about/accessibility.md)
- [Browser support](/docs/about/browser-support.md)
### Sensors ๐
> The ways in which somebody can start and control a drag
- [Mouse dragging ๐ญ](/docs/sensors/mouse.md)
- [Touch dragging ๐๐ฑ](/docs/sensors/touch.md)
- [Keyboard dragging ๐นโฟ๏ธ](/docs/sensors/keyboard.md)
- [Create your own sensor](/docs/sensors/sensor-api.md) (allows for any input type as well as scripted experiences)
### API ๐๏ธโ
- [`<DragDropContext />`](/docs/api/drag-drop-context.md) - _Wraps the part of your application you want to have drag and drop enabled for_
- [`<Droppable />`](/docs/api/droppable.md) - _An area that can be dropped into. Contains `<Draggable />`s_
- [`<Draggable />`](/docs/api/draggable.md) - _What can be dragged around_
- [`resetServerContext()`](/docs/api/reset-server-context.md) - _Utility for server side rendering (SSR)_
### Guides ๐บ
- [`<DragDropContext />` responders](/docs/guides/responders.md) - _`onDragStart`, `onDragUpdate`, `onDragEnd` and `onBeforeDragStart`_
- [Combining `<Draggable />`s](/docs/guides/combining.md)
- [Common setup issues](/docs/guides/common-setup-issues.md)
- [Using `innerRef`](/docs/guides/using-inner-ref.md)
- [Setup problem detection and error recovery](/docs/guides/setup-problem-detection-and-error-recovery.md)
- [Rules for `draggableId` and `droppableId`s](/docs/guides/identifiers.md)
- [Browser focus retention](/docs/guides/browser-focus.md)
- [Customising or skipping the drop animation](/docs/guides/drop-animation.md)
- [Auto scrolling](/docs/guides/auto-scrolling.md)
- [Controlling the screen reader](/docs/guides/screen-reader.md)
- [Use the html5 `doctype`](/docs/guides/doctype.md)
- [`TypeScript`: type information](/docs/guides/types.md)
- [Dragging `<svg>`s](/docs/guides/dragging-svgs.md)
- [Avoiding image flickering](/docs/guides/avoiding-image-flickering.md)
- [Non-visible preset styles](/docs/guides/preset-styles.md)
- [How we detect scroll containers](/docs/guides/how-we-detect-scroll-containers.md)
- [How we use dom events](/docs/guides/how-we-use-dom-events.md) - _Useful if you need to build on top of `@hello-pangea/dnd`_
- [Adding `<Draggable />`s during a drag (11.x behaviour)](/docs/guides/changes-while-dragging.md) - _โ ๏ธ Advanced_
- [Setting up Content Security Policy](/docs/guides/content-security-policy.md)
### Patterns ๐ทโ
- [Virtual lists ๐พ](/docs/patterns/virtual-lists.md)
- [Multi drag](/docs/patterns/multi-drag.md)
- [Tables](/docs/patterns/tables.md)
- [Reparenting a `<Draggable />`](/docs/guides/reparenting.md) - _Using our cloning API or your own portal_
### Support ๐ฉโโ๏ธ
- [Engineering health](/docs/support/engineering-health.md)
- [Community and addons](/docs/support/community-and-addons.md)
- [Release notes and changelog](https://github.com/hello-pangea/dnd/releases)
- [Upgrading](/docs/support/upgrading.md)
- [Road map](https://github.com/hello-pangea/dnd/issues)
- [Media](/docs/support/media.md)
## Read this in other languages ๐
โ ๏ธ These following translations are based on [react-beautiful-dnd](https://github.com/atlassian/react-beautiful-dnd).
- [ **ํ๊ธ/Korean**](https://github.com/LeeHyungGeun/react-beautiful-dnd-kr)
- [ **ะะฐ ััััะบะพะผ/Russian**](https://github.com/vtereshyn/react-beautiful-dnd-ru)
- [ **Portuguรชs/Portuguese**](https://github.com/dudestein/react-beautiful-dnd-pt)
- [ **ฮฮปฮปฮทฮฝฮนฮบฮฌ/Greek**](https://github.com/milvard/react-beautiful-dnd-gr)
## Creator โ๏ธ
Alex Reardon [@alexandereardon](https://twitter.com/alexandereardon)
> Alex is no longer personally maintaning this project. The other wonderful maintainers are carrying this project forward.
## Maintainers ๐ ๏ธ
- Gabriel Santerre [@100terres](https://github.com/100terres)
- Reece Carolan [@Xhale1](https://github.com/Xhale1)
- Many [@Atlassian](https://twitter.com/Atlassian)'s have contributed to the original [`react-beautiful-dnd`](https://github.com/atlassian/react-beautiful-dnd). _Atlassian is no longer involved with this project._
## Collaborators ๐ค
- Bogdan Chadkin [@IAmTrySound](https://twitter.com/IAmTrySound)
## Thanks ๐ค
<a href="https://www.chromatic.com/"><img src="https://user-images.githubusercontent.com/321738/84662277-e3db4f80-af1b-11ea-88f5-91d67a5e59f6.png" width="153" height="30" alt="Chromatic" /></a>
Thanks to [Chromatic](https://www.chromatic.com/) for providing the visual testing platform that helps us review UI changes and catch visual regressions.