Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Port @uppy/drop-target docs #59

Merged
merged 6 commits into from
Jan 24, 2023
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 117 additions & 0 deletions docs/user-interfaces/elements/drop-target.mdx
Original file line number Diff line number Diff line change
@@ -1 +1,118 @@
---
sidebar_position: 2
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

import UppyCdnExample from '/src/components/UppyCdnExample';

# Drop target

The `@uppy/drop-target` plugin lets your users drag-and-drop files on any
element on the page, for example the whole page, `document.body`.

Can be used together with Uppy Dashboard or Drag & Drop plugins, or your custom
solution, including plain text “please drop files here”.
aduh95 marked this conversation as resolved.
Show resolved Hide resolved

```js
import DropTarget from '@uppy/drop-target';

uppy.use(DropTarget, {
target: document.body,
});
```

:::tip

[Try out the live example](/examples) or take it for a spin in
[CodeSandbox](https://codesandbox.io/s/uppy-drag-drop-gyewzx?file=/src/index.js).
Comment on lines +20 to +21
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/examples doesn't exit. We should also create a codesandbox for this plugin and link it here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We plan to have something at /examples don't we?

{ to: '/examples', label: 'Examples', position: 'left' },

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No as discussed we will go live without it and potentially never have it as we emphasize our existing examples repo and codesandboxes. So at least for now we need to remove it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should also create a codesandbox for this plugin and link it here.

I don't know what's needed for this. We should probably document some guidelines around it.

No as discussed we will go live without it and potentially never have it as we emphasize our existing examples repo and codesandboxes.

There are 12 other pages linking to /examples, plus the main nav menu cited above. I don't think it makes sense to remove it from this PR. If we plan to remove them before going live, it can be done in a follow-up PR and doesn't have to block this one.


:::

## Installation

This plugin is published as the `@uppy/drop-target` package on the npm registry.
aduh95 marked this conversation as resolved.
Show resolved Hide resolved

<Tabs>
<TabItem value="npm" label="NPM" default>

```shell
npm install @uppy/drop-target
```

</TabItem>

<TabItem value="yarn" label="Yarn">

```shell
yarn add @uppy/drop-target
```

</TabItem>

<TabItem value="cdn" label="CDN">
<UppyCdnExample>
{`
import { DropTarget } from "{{UPPY_JS_URL}}"
const DropTarget = new Uppy().use(DropTarget)
`}
</UppyCdnExample>
</TabItem>
</Tabs>

## Use

This module has one default export: the `RemoteSources` plugin class.

## CSS

The `@uppy/drop-target` plugin includes some basic styles for
`uppy-is-drag-over` CSS class name. You can also choose not to use it and
provide your own styles instead.

```js
import '@uppy/core/dist/style.css';
import '@uppy/drop-target/dist/style.css';
```

Import general Core styles from `@uppy/core/dist/style.css` first, then add the
Drag & Drop styles from `@uppy/drop-target/dist/style.css`. A minified version
is also available as `style.min.css` at the same path. The way to do import
depends on your build system.

## Options

The `@uppy/drop-target` plugin has the following configurable options:

```js
uppy.use(DropTarget, {
target: null,
onDragOver: (event) => {},
onDrop: (event) => {},
onDragLeave: (event) => {},
});
```

### `target: null`

DOM element or CSS selector to attach the drag and drop listeners to.

### `onDragOver(event)`

Event listener for the [`dragover` event][].

### `onDrop(event)`

Event listener for the [`drop` event][].

### `onDragLeave(event)`

Event listener for the [`dragleave` event][].

[`dragover` event]:
https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dragover_event
[`dragleave` event]:
https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dragleave_event
[`drop` event]:
https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/drop_event