sp-dropzone

Examples API

Attributes and Properties #

Property Attribute Type Default Description
dir dir 'ltr' | 'rtl' 'ltr'
isDragged dragged boolean false
dropEffect dropEffect 'copy' | 'move' | 'link' | 'none' Controls the feedback (typically visual) the user is given during a drag and drop operation

Slots #

Name Description
default slot The default slot on an `sp-dropzone` is a great place to place upload instructions built with an `sp-illustrated-message` or other information, possibly even built from data provided by the upload, to support users successfully interacting with the drag and drop based features of your application

Events #

Name Type Description
sp-dropzone-dragleave Event Announces when dragged files have been moved out of the UI without having been dropped.
sp-dropzone-dragover Event Announces when files have been dragged over the UI, but not yet dropped.
sp-dropzone-drop Event Announces when dragged files have been dropped on the UI.
sp-dropzone-should-accept Event A cancellable event that confirms whether or not a file dropped on the UI should be accepted.

CSS Custom Properties #

Name Default
--spectrum-dropzone-background-color-selected-hover var(--spectrum-alias-highlight-selected)
--spectrum-dropzone-border-color var(--spectrum-global-color-gray-300)
--spectrum-dropzone-border-color-selected-hover var(--spectrum-global-color-blue-400)
--spectrum-dropzone-border-radius var(--spectrum-alias-border-radius-regular)
--spectrum-dropzone-border-width var(--spectrum-alias-border-size-thick)
--spectrum-dropzone-padding var(--spectrum-global-dimension-size-900)

Description #

A <sp-dropzone> is an area on the screen into which an object can be dragged and dropped to accomplish a task. For example, a DropZone might be used in an upload workflow to enable the user to drop a file from their operating system into the DropZone, which is a more efficient and intuitive action, rather than utilize the standard "Choose File" dialog.

DropZones should be used with an IllustratedMessage component as a child if the drop zone is empty, otherwise the existing content should be passed as a child.

Usage #

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/dropzone

Import the side effectful registration of <sp-dropzone> via:

import '@spectrum-web-components/dropzone/sp-dropzone.js';

When looking to leverage the Dropzone base class as a type and/or for extension purposes, do so via:

import { Dropzone } from '@spectrum-web-components/dropzone';

Example #

<sp-dropzone id="dropzone-1" style="width: 400px; height: 200px">
<sp-illustrated-message heading="Drag and Drop Your File">
<svg
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 150 103"
width="150"
height="103"
>

<path
d="M133.7,8.5h-118c-1.9,0-3.5,1.6-3.5,3.5v27c0,0.8,0.7,1.5,1.5,1.5s1.5-0.7,1.5-1.5V23.5h119V92c0,0.3-0.2,0.5-0.5,0.5h-118c-0.3,0-0.5-0.2-0.5-0.5V69c0-0.8-0.7-1.5-1.5-1.5s-1.5,0.7-1.5,1.5v23c0,1.9,1.6,3.5,3.5,3.5h118c1.9,0,3.5-1.6,3.5-3.5V12C137.2,10.1,135.6,8.5,133.7,8.5z M15.2,21.5V12c0-0.3,0.2-0.5,0.5-0.5h118c0.3,0,0.5,0.2,0.5,0.5v9.5H15.2z M32.6,16.5c0,0.6-0.4,1-1,1h-10c-0.6,0-1-0.4-1-1s0.4-1,1-1h10C32.2,15.5,32.6,15.9,32.6,16.5z M13.6,56.1l-8.6,8.5C4.8,65,4.4,65.1,4,65.1c-0.4,0-0.8-0.1-1.1-0.4c-0.6-0.6-0.6-1.5,0-2.1l8.6-8.5l-8.6-8.5c-0.6-0.6-0.6-1.5,0-2.1c0.6-0.6,1.5-0.6,2.1,0l8.6,8.5l8.6-8.5c0.6-0.6,1.5-0.6,2.1,0c0.6,0.6,0.6,1.5,0,2.1L15.8,54l8.6,8.5c0.6,0.6,0.6,1.5,0,2.1c-0.3,0.3-0.7,0.4-1.1,0.4c-0.4,0-0.8-0.1-1.1-0.4L13.6,56.1z"
>
</path>
</svg>
</sp-illustrated-message>

<div>
<label for="file-input" onclick="this.nextElementSibling.click()">
<sp-link href="javascript:;">Select a File</sp-link>
from your computer
</label>
<input type="file" id="file-input" style="display: none" />
</div>
<div>
or
<sp-link href="http://stock.adobe.com" target="blank">
Search Adobe Stock
</sp-link>
</div>
</sp-dropzone>

Dragged #

When a file is dragged over the <sp-dropzone> element, it will display with the dragged attribute, as follows:

<sp-dropzone id="dropzone" dragged style="width: 400px; height: 200px">
<sp-illustrated-message heading="Drag and Drop Your File">
<svg
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 150 103"
width="150"
height="103"
>

<path
d="M133.7,8.5h-118c-1.9,0-3.5,1.6-3.5,3.5v27c0,0.8,0.7,1.5,1.5,1.5s1.5-0.7,1.5-1.5V23.5h119V92c0,0.3-0.2,0.5-0.5,0.5h-118c-0.3,0-0.5-0.2-0.5-0.5V69c0-0.8-0.7-1.5-1.5-1.5s-1.5,0.7-1.5,1.5v23c0,1.9,1.6,3.5,3.5,3.5h118c1.9,0,3.5-1.6,3.5-3.5V12C137.2,10.1,135.6,8.5,133.7,8.5z M15.2,21.5V12c0-0.3,0.2-0.5,0.5-0.5h118c0.3,0,0.5,0.2,0.5,0.5v9.5H15.2z M32.6,16.5c0,0.6-0.4,1-1,1h-10c-0.6,0-1-0.4-1-1s0.4-1,1-1h10C32.2,15.5,32.6,15.9,32.6,16.5z M13.6,56.1l-8.6,8.5C4.8,65,4.4,65.1,4,65.1c-0.4,0-0.8-0.1-1.1-0.4c-0.6-0.6-0.6-1.5,0-2.1l8.6-8.5l-8.6-8.5c-0.6-0.6-0.6-1.5,0-2.1c0.6-0.6,1.5-0.6,2.1,0l8.6,8.5l8.6-8.5c0.6-0.6,1.5-0.6,2.1,0c0.6,0.6,0.6,1.5,0,2.1L15.8,54l8.6,8.5c0.6,0.6,0.6,1.5,0,2.1c-0.3,0.3-0.7,0.4-1.1,0.4c-0.4,0-0.8-0.1-1.1-0.4L13.6,56.1z"
>
</path>
</svg>
</sp-illustrated-message>

<div>
<label for="file-input" onclick="this.nextElementSibling.click()">
<sp-link href="javascript:;">Select a File</sp-link>
from your computer
</label>
<input type="file" id="file-input" style="display: none" />
</div>
<div>
or
<sp-link href="http://stock.adobe.com" target="blank">
Search Adobe Stock
</sp-link>
</div>
</sp-dropzone>

Accessibility #

When actions, e.g. copy/paste, can be enacted directly on the <sp-dropzone> element itself, be sure to supply a tabindex so that keyboard users can find this interaction in the tab order. For screen readers, supply appropriate role and aria-label attributes to clarify what these actions are and how to complete them.