sp-dropzone

NPM 1.0.1

View Storybook

Try it on webcomponents.dev
Overview API Changelog

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;">
    <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">
            <sp-link
                href="javascript:;"
                onclick="this.parentElement.nextElementSibling.click()"
            >
                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;">
    <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">
            <sp-link
                href="javascript:;"
                onclick="this.parentElement.nextElementSibling.click()"
            >
                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>

Filled

When the <sp-dropzone> is in a filled state, set the filled attribute, as follows:

<sp-action-button draggable="true" style="margin-block-end: 16px;">
    Drag me
</sp-action-button>
<sp-dropzone tabindex="0" id="dropzone" drop-effect="copy">
    <sp-illustrated-message style="--mod-illustrated-message-display: flex;" heading="Drag and drop your file" id="message">
     <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">
            <sp-link
                href="javascript:;"
                onclick="this.parentElement.nextElementSibling.click()"
            >
                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>

<script type="module">
    customElements.whenDefined('sp-dropzone').then(() => {
        const dropzone = document.getElementById('dropzone');
        const message = document.getElementById('message');
        const fileInput = document.getElementById('file-input');
        let input;
        let beingDraggedOver = false;

        const updateMessage = () => {
            message.heading = input !== undefined
                ? (beingDraggedOver ? 'Drop here to replace!' : 'You dropped something!')
                : 'Drag and drop your file';
        };

        const handleDropOrChange = () => {
            input = 'mock-file';
            dropzone.setAttribute("filled", true);
            beingDraggedOver = false;
            updateMessage();
        };

        dropzone.addEventListener('dragover', (event) => {
            event.preventDefault();
            beingDraggedOver = true;
            updateMessage();
        });

        dropzone.addEventListener('dragleave', () => {
            beingDraggedOver = false;
            updateMessage();
        });

        dropzone.addEventListener('drop', (event) => {
            event.preventDefault();
            handleDropOrChange();
        });

        fileInput.addEventListener('change', handleDropOrChange);
    });
</script>

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, be sure to announce what the actions are, how to complete them, and when they are completed by supplying the appropriate role and aria-label attributes.

Attributes and Properties

Property Attribute Type Default Description isDragged dragged boolean false Indicates that files are currently being dragged over the dropzone. dropEffect dropEffect 'copy' | 'move' | 'link' | 'none' Controls the feedback (typically visual) the user is given during a drag and drop operation isFilled filled boolean false Set this property to indicate that the component is in a filled state.

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.

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/dropzone

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/dropzone

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/dropzone

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/dropzone

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/dropzone

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/dropzone

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/dropzone

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/dropzone

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/dropzone

0.45.0 (2024-07-30)

Features

  • add filled state to dropzone component (#4617) (f6b7144)

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/dropzone

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/dropzone

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/dropzone

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/dropzone

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/dropzone

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/dropzone

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/dropzone

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/dropzone

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/dropzone

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/dropzone

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/dropzone

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/dropzone

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/dropzone

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/dropzone

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/dropzone

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/dropzone

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/dropzone

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/dropzone

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/dropzone

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/dropzone

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/dropzone

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/dropzone

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/dropzone

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/dropzone

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/dropzone

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/dropzone

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/dropzone

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/dropzone

0.32.0 (2023-06-01)

Features

  • dropzone: use core tokens (11f7560)

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/dropzone

0.30.0 (2023-05-03)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)
  • dropzone: show dragged color in new illustratedmessage version (0591acf)
  • ensure browser understandable extensions (f4e59f7)
  • include "type" in package.json, generate custom-elements.json (1a8d716)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • move hover/focus hoisting into conditioning (15ac2f7)
  • normalize "event" and "error" argument names (8d382cd)
  • remove ":" based namespacing of events (d77a843)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-group: add action-group pattern (d2de766)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • dropzone: update spectrum css input (0f5a667)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use :focus-visable (via polyfill) instead of :focus (11c6fc7)
  • use @adobe/spectrum-css@2.15.1 (3918888)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)
  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

Reverts

  • Revert "chore: release new versions" (a6d655d)

0.10.9 (2023-04-24)

Bug Fixes

  • dropzone: show dragged color in new illustratedmessage version (0591acf)

0.10.8 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/dropzone

0.10.7 (2023-03-22)

Bug Fixes

  • move hover/focus hoisting into conditioning (15ac2f7)

0.10.6 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/dropzone

0.10.5 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/dropzone

0.10.4 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/dropzone

0.10.3 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/dropzone

0.10.2 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/dropzone

0.10.1 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/dropzone

0.10.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.9.11 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.10 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.9 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.8 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.7 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.6 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.5 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.4 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.3 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.2 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/dropzone

0.9.0 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/dropzone

0.8.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/dropzone

0.8.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.7.10 (2021-10-12)

Note: Version bump only for package @spectrum-web-components/dropzone

0.7.9 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/dropzone

0.7.8 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.7.7 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/dropzone

0.7.6 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/dropzone

0.7.5 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/dropzone

0.7.4 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/dropzone

0.7.3 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/dropzone

0.7.2 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/dropzone

0.7.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/dropzone

0.7.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.6.1 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.6.0 (2021-01-21)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • dropzone: update spectrum css input (0f5a667)

0.5.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • dropzone: update spectrum css input (0f5a667)

0.4.4 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/dropzone

0.4.3 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.4.2 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.4.1 (2020-09-14)

Note: Version bump only for package @spectrum-web-components/dropzone

0.4.0 (2020-08-31)

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • action-group: add action-group pattern (d2de766)

0.3.1 (2020-08-19)

Bug Fixes

  • ensure browser understandable extensions (f4e59f7)

0.3.0 (2020-07-17)

Features

  • leverage "exports" field in package.json (321abd7)

0.2.7 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/dropzone

0.2.6 (2020-04-16)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.2.5 (2020-04-07)

Note: Version bump only for package @spectrum-web-components/dropzone

0.2.4 (2020-03-11)

Note: Version bump only for package @spectrum-web-components/dropzone

0.2.3 (2020-01-06)

Note: Version bump only for package @spectrum-web-components/dropzone

0.2.2 (2019-12-02)

Bug Fixes

  • normalize "event" and "error" argument names (8d382cd)

0.2.1 (2019-11-27)

Bug Fixes

  • include "type" in package.json, generate custom-elements.json (1a8d716)

0.2.0 (2019-11-19)

Features

  • use :focus-visable (via polyfill) instead of :focus (11c6fc7)
  • use @adobe/spectrum-css@2.15.1 (3918888)

0.1.5 (2019-11-01)

Bug Fixes

  • remove ":" based namespacing of events (d77a843)

0.1.4 (2019-10-14)

Performance Improvements

  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

0.1.3 (2019-10-03)

Note: Version bump only for package @spectrum-web-components/dropzone