# swc-dropzone

A drop zone is a target area that accepts dragged-and-dropped content, typically files, from the operating system or from within the same page.

```js
import '@adobe/spectrum-wc/components/dropzone/index.js';
// <swc-dropzone></swc-dropzone>
```

## Attributes

| Name              | Type                                   | Default                           | Description                                                                                                                                                                           |
| ----------------- | -------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dragged-message` | `string`                               | `'File ready to drop'`            | Message announced via the built-in status region when a file is dragged over an empty drop zone. Override to localize.                                                                |
| `filled-message`  | `string`                               | `'File accepted'`                 | Message announced via the built-in status region when a file is accepted. Override to localize.                                                                                       |
| `replace-message` | `string`                               | `'Drop to replace existing file'` | Message announced via the built-in status region when a file is dragged over an already-filled drop zone. Override to localize.                                                       |
| `size`            | `ElementSize`                          | -                                 | Controls the illustrated icon scale and container dimensions.                                                                                                                         |
| `dragged`         | `boolean`                              | `false`                           | Whether files are currently being dragged over the drop zone. Set automatically by the component; also settable to reflect programmatic state.                                        |
| `filled`          | `boolean`                              | `false`                           | Whether the drop zone has received a file and is in the filled state. Set by consuming code after a successful drop or browse-file selection to switch the zone to its filled visual. |
| `drop-effect`     | `'copy' \| 'move' \| 'link' \| 'none'` | `'copy'`                          | The OS drag-cursor feedback shown while a file is held over the zone. Maps directly to `DataTransfer.dropEffect`.                                                                     |

## Slots

| Name             | Description                                                                                                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `(default)`      | Slot for the illustrated message and browse control. Hidden automatically when `filled` is `true`. A browse button or link **must** always be provided so keyboard users can upload files. |
| `filled-content` | Slot for the uploaded-state content (e.g. an image preview). Shown automatically when `filled` is `true`; hidden otherwise.                                                                |

## Events

| Name                         | Description                                                                                                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `swc-dropzone-should-accept` | Cancelable event fired on every native `dragover` tick while a drag is over the zone, not just on entry. Cancel to reject the dragged payload and set the cursor to `none`. |
| `swc-dropzone-dragover`      | Fired once when dragged files enter the zone and are accepted; does not repeat on subsequent `dragover` ticks while still hovering.                                         |
| `swc-dropzone-dragleave`     | Fired when an accepted drag leaves the zone or becomes rejected.                                                                                                            |
| `swc-dropzone-drop`          | Fired when files are dropped on the zone. Set `filled` in your handler to transition the zone to its filled state.                                                          |

## CSS Custom Properties

| Name                                           | Description                                                                                                                                                        |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--swc-dropzone-background-color`              | Background color of the drop zone. Defaults to transparent; overridden to a subtle accent tint in the dragged state.                                               |
| `--swc-dropzone-border-color`                  | Color of the SVG stroke border. Defaults to the gray-300 token in the default state; overridden to the accent visual color in the dragged and focus-within states. |
| `--swc-dropzone-padding`                       | Padding inside the drop zone. Defaults vary by size: spacing-300 (s), spacing-400 (m), spacing-600 (l).                                                            |
| `--swc-illustrated-message-illustration-color` | Illustration color cascaded into a slotted `swc-illustrated-message`. Unset by default; overridden to the accent-content-color-default token in the dragged state. |