@atlaskit/pragmatic-drag-and-drop-docs
Version:
This package holds the documentation for Pragmatic drag and drop in one place. It is not intended to be consumed directly by consumers. The package is used by other tools for sharing examples
291 lines (219 loc) • 11.7 kB
text/mdx
---
title: Examples
order: 0
---
import { Stack, Inline } from '@atlaskit/primitives';
import SectionMessage from '@atlaskit/section-message';
import { LinkButton } from '@atlaskit/button/new';
import ListExample from '../../examples/list';
import BoardExample from '../../examples/board';
import GridExample from '../../examples/grid';
import TableExample from '../../examples/table';
import FileExample from '../../examples/file';
import DrawingExample from '../../examples/drawing';
import ResizingExample from '../../examples/resizing';
import TreeExample from '../../examples/tree';
import TreeLegacyExample from '../../examples/tree-legacy';
import VirtualListExample from '../../examples/virtual-list';
import { TrelloLikeBoardIframe } from '../../examples/trello-like-board-iframe';
The examples on this page demonstrate _some_ of what is possible with Pragmatic drag and drop.
Pragmatic drag and drop gives you low level building blocks that you can use to make _any_ drag and
drop experience that the web platform supports. The examples use a combination of our
[core package](/components/pragmatic-drag-and-drop/core-package) and
[optional packages](/components/pragmatic-drag-and-drop/optional-packages).
## List
<Example Component={ListExample} appearance="showcase-only" />
### Simple list on other stacks
We have created [simple list example](https://github.com/alexreardon/pdnd-react-tailwind) which does
not leverage any other Atlassian Design System outputs.
<a
href="https://stackblitz.com/github/alexreardon/pdnd-react-tailwind?startScript=dev"
target="_blank"
>
{/* Using inline styles rather than pulling into a seperate component and using emotion
as Gatsby can only load images in `mdx` when they are in the `mdx` document root.*/}
<img
src="/images/pdnd-standalone-simple-example.png"
alt="Simple list example"
style="max-width:400px; border:var(--ds-border-width) solid var(--ds-border-discovery); border-radius:var(--ds-border-radius)"
/>
</a>
In order to demonstrate how to use Pragmatic drag and drop on different tech stacks, the community
has ported this [simple list example](https://github.com/alexreardon/pdnd-react-tailwind) to various
tech stacks:
<details>
<summary>List example ports</summary>
<br />
<SectionMessage appearance="warning">
These examples have been contributed by a mixture of Atlassian and non-Atlassian contributors.
Please use caution when viewing and running these examples.
</SectionMessage>
<br />
<br />
| Technologies | Source | Standalone example | Author(s) |
| ---------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `React` + `TailwindCSS` | [Github](https://github.com/alexreardon/pdnd-react-tailwind) | [Run on StackBlitz](https://stackblitz.com/github/alexreardon/pdnd-react-tailwind?startScript=dev) | [@alexandereardon](https://x.com/alexandereardon) |
| `TailwindCSS` | [Github](https://github.com/alexreardon/pdnd-vanilla-tailwind) | [Run on StackBlitz](https://stackblitz.com/github/alexreardon/pdnd-vanilla-tailwind?startScript=dev) | [@alexandereardon](https://x.com/alexandereardon) |
| `SolidJS` + `TailwindCSS` | [Github](https://github.com/dotnize/pdnd-solid-tailwind) | [Run on StackBlitz](https://stackblitz.com/github/dotnize/pdnd-solid-tailwind?startScript=dev) | [@dotnize](https://github.com/dotnize) |
| `Vue 3` + `TailwindCSS` | [Github](https://github.com/frenicohansen/pdnd-vue) | [Run on StackBlitz](https://stackblitz.com/github/frenicohansen/pdnd-vue?startScript=dev) | [@frenicohansen](https://github.com/frenicohansen) |
| `Vue 3` + `Nuxt 3 (SSR)` + `TailwindCSS` | [Github](https://github.com/frenicohansen/pdnd-nuxt) | [Run on StackBlitz](https://stackblitz.com/github/frenicohansen/pdnd-nuxt?startScript=dev) | [@frenicohansen](https://github.com/frenicohansen) |
</details>
## Board
<Example Component={BoardExample} appearance="showcase-only" />
### Board with shadows
A board example that leverages shadows for drop placement (like [Trello](https://trello.com/)).
<SectionMessage appearance="information">
This example does not have our
[accessibility guidelines](/components/pragmatic-drag-and-drop/accessibility-guidelines) wired up to
keep the code simpler. It is built on [React](https://react.dev/),
[TailwindCSS](https://tailwindcss.com/) (for styling) and [Lucide](https://lucide.dev/) (for icons).
</SectionMessage>
<SectionMessage appearance="warning">
**For Atlassians**: please do not leverage shadows for drop placement in Atlassian experiences.
Trello being the only exception to this rule.
Shadow based drop placement _does not_ follow our
[design guidelines](/components/pragmatic-drag-and-drop/design-guidelines) that have been agreed on
by craft and leadership. Our chosen design affordances have been chosen because they scale well
across a huge variety of experiences in a consistent way. This predictability is important for our
users. Our chosen affordances are also performant and easy to get right.
</SectionMessage>
<TrelloLikeBoardIframe />
## Grid
<SectionMessage appearance="information">
This grid example does a simple "swap" when dropping. You can do whatever operations you like with
grids (including inserting items based on closest edge). This example does not currently have
accessibility wired up.
</SectionMessage>
<Example Component={GridExample} appearance="showcase-only" />
## Table
<SectionMessage appearance="information" title="Needs updating">
Our table example does not line up with our
[latest design guidelines](/components/pragmatic-drag-and-drop/design-guidelines) and needs to be
updated.
</SectionMessage>
<Example Component={TableExample} appearance="showcase-only" />
## Tree
<Example Component={TreeExample} appearance="showcase-only" />
## Tree (legacy)
<SectionMessage>
This tree example (which uses our `tree-item` outputs) is no longer recommended, but you are still
welcome to use it.
We have moved in a different, and more flexible direction with our new `list-item` outputs.
</SectionMessage>
<Example Component={TreeLegacyExample} appearance="showcase-only" />
## File
Use the [external adapter](/components/pragmatic-drag-and-drop/core-package/adapters/external) to
capture files that users drag and drop onto the page.
When requesting files, you should also provide an `<input type="file" />` for usability and
accessibility reasons.
<Example Component={FileExample} appearance="showcase-only" />
## Side navigation
This example shows off how you can add rich drag and drop interactions to a side navigation
experience.
<br />
<a href="/components/navigation-system/side-navigation/drag-and-drop" target="_blank">
{/**
* Why a link?
* - atlassian.design does not support full page examples for us to iframe
* - cannot iframe atlaskit as the example is currently only on staging
* - cannot use relative imports across package boundaries
* - exposing the example on an entry point from navigation-system would impact it's source `dependencies`
*
* Using inline styles as Gatsby can only load images in `mdx` when they are in the `mdx` document root
*/}
<img
src="/images/pdnd-standalone-jira-sidebar.png"
alt="Drag and drop into and out of iframes"
style="max-width:200px; border:var(--ds-border-width) solid var(--ds-border-discovery); border-radius:var(--ds-border-radius)"
/>
</a>
This example leverages our [navigation system package](/components/navigation-system), and has it's
own [specific guidance](/components/pragmatic-drag-and-drop/examples)
## Drawing
<SectionMessage
appearance="information"
title="Excepted from Success Criterion 2.1.1 - Keyboard (Level A)"
>
<Stack space="space.200">
<p>
This example is excepted from the{' '}
<a href="https://www.w3.org/WAI/WCAG21/Understanding/keyboard">
WCAG Success Criterion 2.1.1 - Keyboard (Level A)
</a>
. The underlying function (freehand drawing) requires input that depends on the path of the
user's movement and not just the endpoints.
</p>
<p>
Due to{' '}
<a href="https://www.w3.org/WAI/WCAG21/Understanding/keyboard-no-exception">
Success Criterion 2.1.3 - Keyboard (No Exception) (Level AAA)
</a>
, path-dependent input cannot meet{' '}
<a href="https://www.w3.org/WAI/WCAG21/Understanding/keyboard-accessible">Guideline 2.1</a> at
Level AAA.
</p>
<p>
Wherever possible, this exception should not be relied on, and an alternative input method
should be provided.
</p>
</Stack>
</SectionMessage>
<Example Component={DrawingExample} appearance="showcase-only" />
## Resizing
<SectionMessage appearance="information" title="Accessibility guidance in progress">
<p>
An investigation is required to decide on appropriate accessible controls for resizing. If you
would like us to prioritise this investigation, please reach out.
</p>
</SectionMessage>
<Example Component={ResizingExample} appearance="showcase-only" />
## Virtual
<SectionMessage appearance="success">
<p>
Pragmatic drag an drop works with <strong>any virtual experience</strong>: you can add, remove
or change any entity you want during a drag operation. This example uses{' '}
<a href="https://tanstack.com/virtual/latest">TanStack Virtual</a>, but you can use any
virtualization solution you like.
<br />
See our{' '}
<a href="/components/pragmatic-drag-and-drop/core-package/recipes/virtualization">
virtualization guide
</a>{' '}
for more details.
</p>
</SectionMessage>
<Example Component={VirtualListExample} appearance="showcase-only" />
## Iframes and external applications
Pragmatic drag and drop
[enables you to attach data for external systems](/components/pragmatic-drag-and-drop/core-package/adapters/element/about#data-for-external-consumers-getinitialdataforexternal)
(other brower tabs, iframes or even native applications), as well as
[respond to and recieve data being dragged from external systems](/components/pragmatic-drag-and-drop/core-package/adapters/external/about).
<SectionMessage title="External example">
`atlassian.design` currently does not support displaying an example without the page layout, so our
iframe example is hosted on another site.
</SectionMessage>
<Stack space="space.100">
<a
href="https://atlaskit.atlassian.com/example?groupId=pragmatic-drag-and-drop&packageId=documentation&exampleId=iframe-board&mode=dark"
target="_blank"
>
{/* Using inline styles rather than pulling into a seperate component and using emotion
as Gatsby can only load images in `mdx` when they are in the `mdx` document root.*/}
<img
src="/images/pdnd-iframe-example.png"
alt="Drag and drop into and out of iframes"
style="max-width:400px; border:var(--ds-border-width) solid var(--ds-border-discovery); border-radius:var(--ds-border-radius)"
/>
</a>
<Inline space="space.100">
<a
href="https://github.com/atlassian/pragmatic-drag-and-drop/blob/main/packages/documentation/examples/iframe-board.tsx"
target="_blank"
>
View source
</a>
<a href="https://www.youtube.com/watch?v=E4l4MBO-Bwg" target="_blank">
Presentation
</a>
</Inline>
</Stack>