Dropzone
---import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";---
<div class="w-full max-w-[400px]"> <Dropzone /></div>import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
export function Example() { return ( <div className="w-full max-w-[400px]"> <Dropzone /> </div> );}<script setup lang="ts">import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator,} from "@/components/starwind/dropzone";</script>
<template> <div class="w-full max-w-[400px]"> <Dropzone /> </div></template><script lang="ts"> import { Dropzone } from "@/components/starwind/dropzone";</script>
<div class="w-full max-w-[400px]"> <Dropzone /></div>Installation
pnpx starwind@latest add dropzone --framework astronpx starwind@latest add dropzone --framework astroyarn dlx starwind@latest add dropzone --framework astropnpx starwind@latest add dropzone --framework reactnpx starwind@latest add dropzone --framework reactyarn dlx starwind@latest add dropzone --framework reactpnpx starwind@latest add dropzone --framework vuenpx starwind@latest add dropzone --framework vueyarn dlx starwind@latest add dropzone --framework vuepnpx starwind@latest add dropzone --framework sveltenpx starwind@latest add dropzone --framework svelteyarn dlx starwind@latest add dropzone --framework svelteUsage
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.
---import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";---
<Dropzone />import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
export function Example() { return ( <> <Dropzone /> </> );}<script setup lang="ts">import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator,} from "@/components/starwind/dropzone";</script>
<template> <Dropzone /></template><script lang="ts"> import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator, } from "@/components/starwind/dropzone";</script>
<Dropzone />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>import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
export function Example() { return ( <Dropzone> <DropzoneUploadIndicator /> <DropzoneLoadingIndicator /> <DropzoneFilesList /> </Dropzone> );}<script setup lang="ts">import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator,} from "@/components/starwind/dropzone";</script>
<template> <Dropzone> <DropzoneUploadIndicator /> <DropzoneLoadingIndicator /> <DropzoneFilesList /> </Dropzone></template><script lang="ts"> import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator, } from "@/components/starwind/dropzone";</script>
<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.
---import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";---
<Dropzone> <DropzoneUploadIndicator> <span class="my-6 text-lg">Your specific message</span> </DropzoneUploadIndicator> <DropzoneLoadingIndicator /> <DropzoneFilesList /></Dropzone>import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
export function Example() { return ( <> <Dropzone> <DropzoneUploadIndicator> <span className="my-6 text-lg">Your specific message</span> </DropzoneUploadIndicator> <DropzoneLoadingIndicator /> <DropzoneFilesList /> </Dropzone> </> );}<script setup lang="ts">import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator,} from "@/components/starwind/dropzone";</script>
<template> <Dropzone> <DropzoneUploadIndicator> <span class="my-6 text-lg">Your specific message</span> </DropzoneUploadIndicator> <DropzoneLoadingIndicator /> <DropzoneFilesList /> </Dropzone></template><script lang="ts"> import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator, } from "@/components/starwind/dropzone";</script>
<Dropzone> <DropzoneUploadIndicator> <span class="my-6 text-lg">Your specific message</span> </DropzoneUploadIndicator> <DropzoneLoadingIndicator /> <DropzoneFilesList /></Dropzone>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.
---import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";---
<Dropzone isUploading={true} />import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
export function Example() { return ( <> <Dropzone isUploading={true} /> </> );}<script setup lang="ts">import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator,} from "@/components/starwind/dropzone";</script>
<template> <Dropzone :isUploading="true" /></template><script lang="ts"> import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator, } from "@/components/starwind/dropzone";</script>
<Dropzone isUploading={true} />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).
---import { Button } from "@/components/starwind/button";import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator,} from "@/components/starwind/dropzone";---
<div class="flex w-full max-w-[400px] flex-col gap-4"> <form id="dropzone-form-demo" class="space-y-4"> <Dropzone id="my-dropzone" name="dropzone-file" /> <Button type="submit" class="w-full">Submit</Button> </form></div>
<script> function handleFormSubmit() { const form = document.querySelector("#dropzone-form-demo") as HTMLFormElement; const dropzone = document.querySelector("#my-dropzone") as HTMLElement; if (form) { form.addEventListener("submit", (e) => { e.preventDefault();
dropzone.setAttribute("data-is-uploading", "true");
const formData = new FormData(form); const formValues = Object.fromEntries(formData.entries());
// demo form data logging console.log("Form submission values:", formValues);
// You can add additional logic here like: // - Form validation // - API submission // - Success/error handling
// Simulate API submission setTimeout(() => { dropzone.setAttribute("data-is-uploading", "false"); }, 2000); }); } }
handleFormSubmit();
document.addEventListener("astro:after-swap", handleFormSubmit);</script>import type { FormEvent } from "react";import { useState } from "react";import { Button } from "@/components/starwind/button";import { Dropzone } from "@/components/starwind/dropzone";
export function Example() { const [isUploading, setIsUploading] = useState(false);
async function handleSubmit(event: FormEvent<HTMLFormElement>) { event.preventDefault(); setIsUploading(true); console.log( "Form submission values:", Object.fromEntries(new FormData(event.currentTarget).entries()), ); await new Promise((resolve) => setTimeout(resolve, 2000)); setIsUploading(false); }
return ( <div className="flex w-full max-w-[400px] flex-col gap-4"> <form className="space-y-4" onSubmit={handleSubmit}> <Dropzone name="dropzone-file" isUploading={isUploading} /> <Button type="submit" className="w-full">Submit</Button> </form> </div> );}<script setup lang="ts">import { Button } from "@/components/starwind/button";import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator,} from "@/components/starwind/dropzone";import { onBeforeUnmount, ref } from "vue";
const uploading = ref(false);let timer: ReturnType<typeof setTimeout> | undefined;function submit(event: Event) { console.log( "Form submission values:", Object.fromEntries(new FormData(event.currentTarget as HTMLFormElement)), ); uploading.value = true; clearTimeout(timer); timer = setTimeout(() => { uploading.value = false; }, 2000);}onBeforeUnmount(() => clearTimeout(timer));</script>
<template> <div class="flex w-full max-w-[400px] flex-col gap-4"> <form @submit.prevent="submit" id="dropzone-form-demo" class="space-y-4"> <Dropzone :is-uploading="uploading" id="my-dropzone" name="dropzone-file" /> <Button type="submit" class="w-full">Submit</Button> </form> </div></template><script lang="ts"> import { onDestroy } from "svelte"; import { Button } from "@/components/starwind/button"; import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator, } from "@/components/starwind/dropzone";
let uploading = $state(false); let timer: ReturnType<typeof setTimeout> | undefined; function submit(event: Event) { console.log( "Form submission values:", Object.fromEntries(new FormData(event.currentTarget as HTMLFormElement)), ); uploading = true; clearTimeout(timer); timer = setTimeout(() => { uploading = false; }, 2000); } onDestroy(() => clearTimeout(timer));</script>
<div class="flex w-full max-w-[400px] flex-col gap-4"> <form onsubmit={(event) => { event.preventDefault(); submit(event); }} id="dropzone-form-demo" class="space-y-4" > <Dropzone isUploading={uploading} id="my-dropzone" name="dropzone-file" /> <Button type="submit" class="w-full">Submit</Button> </form></div>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.
---import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";---
<Dropzone accept="image/*" />import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
export function Example() { return ( <> <Dropzone accept="image/*" /> </> );}<script setup lang="ts">import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator,} from "@/components/starwind/dropzone";</script>
<template> <Dropzone accept="image/*" /></template><script lang="ts"> import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator, } from "@/components/starwind/dropzone";</script>
<Dropzone accept="image/*" />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.
---import { Dropzone } from "@/components/starwind/dropzone";---
<div class="grid w-full max-w-[400px] gap-2"> <Dropzone id="image-dropzone" accept="image/*" multiple /> <p id="image-dropzone-message" class="text-error text-sm font-medium" aria-live="polite"></p></div>
<script> function initImageDropzone() { const dropzone = document.querySelector<HTMLElement>("#image-dropzone"); const message = document.querySelector<HTMLElement>("#image-dropzone-message"); if (!dropzone || !message) return;
dropzone.addEventListener("starwind:files-reject", (event) => { const { files } = (event as CustomEvent<{ event: DragEvent; files: File[] }>).detail; message.textContent = `Only images can be added. Not added: ${files.map((file) => file.name).join(", ")}`; }); dropzone.addEventListener("starwind:files-change", () => { message.textContent = ""; }); }
initImageDropzone(); document.addEventListener("astro:after-swap", initImageDropzone);</script>import { useState } from "react";import { Dropzone } from "@/components/starwind/dropzone";
export function Example() { const [message, setMessage] = useState("");
return ( <div className="grid w-full max-w-[400px] gap-2"> <Dropzone accept="image/*" multiple onFilesChange={() => setMessage("")} onFilesReject={(files) => setMessage( `Only images can be added. Not added: ${files.map((file) => file.name).join(", ")}`, ) } /> <p className="text-error text-sm font-medium" aria-live="polite"> {message} </p> </div> );}<script setup lang="ts">import { ref } from "vue";import { Dropzone } from "@/components/starwind/dropzone";
const message = ref("");function showRejected(files: File[]) { message.value = `Only images can be added. Not added: ${files.map((file) => file.name).join(", ")}`;}</script>
<template> <div class="grid w-full max-w-[400px] gap-2"> <Dropzone accept="image/*" multiple @files-change="message = ''" @files-reject="showRejected" /> <p class="text-error text-sm font-medium" aria-live="polite">{{ message }}</p> </div></template><script lang="ts"> import { Dropzone } from "@/components/starwind/dropzone";
let message = $state("");</script>
<div class="grid w-full max-w-[400px] gap-2"> <Dropzone accept="image/*" multiple onFilesChange={() => (message = "")} onFilesReject={(files) => { message = `Only images can be added. Not added: ${files.map((file) => file.name).join(", ")}`; }} /> <p class="text-error text-sm font-medium" aria-live="polite">{message}</p></div>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.
---import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";---
<Dropzone multiple />import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator } from "@/components/starwind/dropzone";
export function Example() { return ( <> <Dropzone multiple /> </> );}<script setup lang="ts">import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator,} from "@/components/starwind/dropzone";</script>
<template> <Dropzone multiple /></template><script lang="ts"> import { Dropzone, DropzoneFilesList, DropzoneLoadingIndicator, DropzoneUploadIndicator, } from "@/components/starwind/dropzone";</script>
<Dropzone multiple />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
createDropzonefrom@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 withoutmultiplekeeps 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-rejectevent on the Dropzone. In React and Svelte, useonFilesReject. In Vue, use@files-reject. The event gives you the rejectedfilesand the dropevent. - When Dropzone keeps none of the dropped files, it shows an error border and the root gets a
data-rejectedattribute. The error clears on the next accepted drop, file picker choice,setFilescall, 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.tsnow 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.