Skip to main content

Starwind UI v3.0 is now available! Migration guide

Installation

Usage

Info

No dropped files on this page are uploaded anywhere.

Default

The default Dropzone component displays a cloud upload icon with a prompt to upload files, and shows what files have been selected.

Custom Content

The dropzone components can be customized through slots. The default <Dropzone /> component has the following three components in the slot if nothing is passed:

---
import {
Dropzone,
DropzoneFilesList,
DropzoneLoadingIndicator,
DropzoneUploadIndicator,
} from "@/components/starwind/dropzone";
---
<Dropzone>
<DropzoneUploadIndicator />
<DropzoneLoadingIndicator />
<DropzoneFilesList />
</Dropzone>

The DropzoneUploadIndicator and DropzoneLoadingIndicator each have their own slots to customize the upload and loading indicators. The DropzoneFilesList component can be passed any classes to use.

Loading

Nothing is actually uploaded when a file is selected, as internally a standard html <input type="file"> is used. To show a loading indication initially, you can use the isUploading prop.

You can also use the data-is-uploading attribute to show or hide a loading indicator at any time. This is useful if you want to show a loading indicator while a file is actually being uploaded (like on form submission).

Accept Specific File Types

You can limit the types of files that users can select by using the accept attribute. Dropzone rejects dropped files that do not match accept. When a drop keeps no files, the Dropzone shows an error border.

To tell users why a drop did not add their files, show a message in a live region when the reject event fires. The event detail has the rejected files and the original drop event. Clear the message when the files change.

Multiple Files

Allow users to select multiple files by using the multiple attribute. Without multiple, Dropzone keeps one dropped file and rejects the others through the same reject event.

API Reference

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Dropzone.

Primitive API

Runtime API

Dropzone primitive
createDropzone from @starwind-ui/runtime/dropzone

Changelog

View version history v2.1.0 4 releases

v2.1.0

  • Dropzone now rejects dropped files that do not match accept. A Dropzone without multiple keeps one file and rejects the other dropped files. Before, nothing happened and no event fired.
  • To get the rejected files, listen for the starwind:files-reject event on the Dropzone. In React and Svelte, use onFilesReject. In Vue, use @files-reject. The event gives you the rejected files and the drop event.
  • When Dropzone keeps none of the dropped files, it shows an error border and the root gets a data-rejected attribute. The error clears on the next accepted drop, file picker choice, setFiles call, or form reset.
  • Screen readers do not announce a rejected drop. To tell screen reader users, show a message in a live region when the reject event fires.

v2.0.2

  • Updated the Vue loading icon to match Astro and React.
  • Kept file selection working when the file input is replaced or moves to another form.
  • Reduced the JavaScript loaded by Dropzone when it is used without Field.

v2.0.1

  • The default export in index.ts now has a name, DropzoneParts, so framework tools show a clear name.

v2.0.0

  • Dropzone now gets its behavior from Starwind Runtime. Runtime handles drag and drop, the file input, and the component state.
  • See the Dropzone Primitive for the unstyled parts and the behavior API.