On this page

Dropzone Primitive

Dropzone is a Starwind Runtime primitive in the form-value-control contract family. Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.

Anatomy

Use the Astro primitive adapter to render Dropzone anatomy with the Runtime wiring included.

---
import { Dropzone } from "@starwind-ui/astro/dropzone";
---

<Dropzone.Root>
  <Dropzone.Input />
  <Dropzone.UploadIndicator>Drop files here</Dropzone.UploadIndicator>
  <Dropzone.LoadingIndicator>Uploading...</Dropzone.LoadingIndicator>
  <Dropzone.FilesList />
</Dropzone.Root>

Use the React primitive adapter when Dropzone state participates in React rendering.

import { Dropzone } from "@starwind-ui/react/dropzone";

export function Example() {
  return (
    <Dropzone.Root>
      <Dropzone.Input />
      <Dropzone.UploadIndicator>Drop files here</Dropzone.UploadIndicator>
      <Dropzone.LoadingIndicator>Uploading...</Dropzone.LoadingIndicator>
      <Dropzone.FilesList />
    </Dropzone.Root>
  );
}

Render the Dropzone data-sw-* contract yourself, then initialize createDropzone.

<label data-sw-dropzone role="button">
  <input data-sw-dropzone-input type="file" tabindex="-1" class="sr-only" />
  <div data-sw-dropzone-upload-indicator>Drop files here</div>
  <div data-sw-dropzone-loading-indicator hidden>Uploading...</div>
  <div data-sw-dropzone-files-list></div>
</label>

<script type="module">
  import { createDropzone } from "@starwind-ui/runtime/dropzone";

  const root = document.querySelector("[data-sw-dropzone]");
  if (root) {
    createDropzone(root);
  }
</script>

API Reference

Root

The main element that owns the Dropzone Runtime instance.

Default element: label
Discovery hook: data-sw-dropzone
Role: button

Props

Prop Type Default

disabled boolean false

Description: Disables the Root part.
Kind: option
Targets: -
Full type: boolean

isUploading boolean false

Description

Controls whether Dropzone is uploading.

Kind

control

Targets

root, uploadIndicator, loadingIndicator

Full type

boolean

React

Use isUploading for controlled state.

isUploading

Astro

Use isUploading for initial state and call setUploading for later updates.

isUploading
setUploading

Runtime / HTML

Use data-is-uploading for initial state and call setUploading for later updates.

data-is-uploading
setUploading

onFilesChange (files: File[], details: DropzoneFilesChangeDetails) => void -

Description: Runs when selected files change for Dropzone.
Kind: callback
Targets: -
Full type: (files: File[], details: DropzoneFilesChangeDetails) => void

Events

Event Callback Value

filesChange onFilesChange files: File[]

Description: Fires when selected files change for Dropzone.
DOM event: starwind:files-change
Details type: DropzoneFilesChangeDetails
Timing: -
Cancelable: No

State

State Type Props

uploading boolean isUploading

Description

Tracks whether Dropzone is uploading files.

Initial attribute

data-is-uploading

Runtime getter

getUploading

Runtime setter

setUploading

React

Use isUploading for controlled state.

isUploading

Astro

Use isUploading for initial state and call setUploading for later updates.

isUploading
setUploading

Runtime / HTML

Use data-is-uploading for initial state and call setUploading for later updates.

data-is-uploading
setUploading

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-dropzone - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-drag-active - Reflects the drag active state on the Root part.

data-has-files - Reflects the has files state on the Root part.

Metadata

Attribute Value Description

data-disabled - Reflects the disabled prop on the Root part.

data-is-uploading - Reflects the uploading prop on the Root part.

Input

The native input synchronized by Dropzone.

Default element: input
Discovery hook: data-sw-dropzone-input
Role: -

Props

Prop Type Default

accept string -

Description: Limits which file types can be selected.
Kind: attribute
Targets: input
Full type: string

multiple boolean -

Description: Allows multiple Dropzone values to be selected.
Kind: attribute
Targets: input
Full type: boolean

name string -

Description: Sets the submitted form field name.
Kind: attribute
Targets: input
Full type: string

required boolean -

Description: Marks the form control as required.
Kind: attribute
Targets: input
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-dropzone-input - Marks the Input part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-disabled - Reflects the disabled prop on the Input part.

Upload Indicator

Upload progress indicator shown by Dropzone.

Default element: div
Discovery hook: data-sw-dropzone-upload-indicator
Role: -

Props

Prop Type Default

isUploading boolean false

Description

Controls whether Dropzone is uploading.

Kind

control

Targets

root, uploadIndicator, loadingIndicator

Full type

boolean

React

Use isUploading for controlled state.

isUploading

Astro

Use isUploading for initial state and call setUploading for later updates.

isUploading
setUploading

Runtime / HTML

Use data-is-uploading for initial state and call setUploading for later updates.

data-is-uploading
setUploading

State

State Type Props

uploading boolean isUploading

Description

Tracks whether Dropzone is uploading files.

Initial attribute

data-is-uploading

Runtime getter

getUploading

Runtime setter

setUploading

React

Use isUploading for controlled state.

isUploading

Astro

Use isUploading for initial state and call setUploading for later updates.

isUploading
setUploading

Runtime / HTML

Use data-is-uploading for initial state and call setUploading for later updates.

data-is-uploading
setUploading

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-dropzone-upload-indicator - Marks the Upload Indicator part so Starwind Runtime can find it.

State

Attribute Value Description

data-is-uploading - Reflects the uploading state on the Upload Indicator part.

Loading Indicator

Loading indicator shown by Dropzone.

Default element: div
Discovery hook: data-sw-dropzone-loading-indicator
Role: -

Props

Prop Type Default

isUploading boolean false

Description

Controls whether Dropzone is uploading.

Kind

control

Targets

root, uploadIndicator, loadingIndicator

Full type

boolean

React

Use isUploading for controlled state.

isUploading

Astro

Use isUploading for initial state and call setUploading for later updates.

isUploading
setUploading

Runtime / HTML

Use data-is-uploading for initial state and call setUploading for later updates.

data-is-uploading
setUploading

State

State Type Props

uploading boolean isUploading

Description

Tracks whether Dropzone is uploading files.

Initial attribute

data-is-uploading

Runtime getter

getUploading

Runtime setter

setUploading

React

Use isUploading for controlled state.

isUploading

Astro

Use isUploading for initial state and call setUploading for later updates.

isUploading
setUploading

Runtime / HTML

Use data-is-uploading for initial state and call setUploading for later updates.

data-is-uploading
setUploading

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-dropzone-loading-indicator - Marks the Loading Indicator part so Starwind Runtime can find it.

State

Attribute Value Description

data-is-uploading - Reflects the uploading state on the Loading Indicator part.

Files List

Lists the selected files for Dropzone.

Default element: div
Discovery hook: data-sw-dropzone-files-list
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-dropzone-files-list - Marks the Files List part so Starwind Runtime can find it.

State

Attribute Value Description

data-has-files - Reflects the has files state on the Files List part.

Runtime API

Factory: createDropzone
Import: @starwind-ui/runtime/dropzone
Root hook: root data-sw-dropzone
Option props: disabled, isUploading, onFilesChange

Option Lifecycles

Option	Lifecycle
disabled	setter-backed
isUploading	setter-backed
onFilesChange	constructor-only

Runtime Setters

Method Target Description

setDisabled prop: disabled Updates whether Dropzone is disabled from Runtime code.

setUploading prop: isUploading Updates whether Dropzone is uploading files from Runtime code.

Form Participation

Fact	Value
Form props	accept, multiple, name, required
Hidden input	input (file)
Field integration	No

Component Relationship

Dropzone Direct primitive

Changelog

View version history v1.0.0 3 releases

v1.0.0

Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.

v0.1.1

Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.

v0.1.0

Introduced drag-and-drop state, file-input coordination, acceptance checks, and file-change events.

Layer Metadata

Dropzone Primitive uses createDropzone. Styled components: Dropzone.

primitive Dropzone Primitive Dropzone Primitive uses createDropzone. Styled components: Dropzone. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters dropzone Dropzone Form Value Control Controls that participate directly in form value submission. /docs/primitives/dropzone/ createDropzone @starwind-ui/runtime/dropzone /docs/runtime/#create-dropzone root disabled isUploading onFilesChange raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Dropzone data-sw-* contract yourself, then initialize createDropzone. html Use the Astro primitive adapter to render Dropzone anatomy with the Runtime wiring included. Use the React primitive adapter when Dropzone state participates in React rendering. tsx label data-sw-dropzone button boolean Disables the Root part. Controls whether Dropzone is uploading. (files: File[], details: DropzoneFilesChangeDetails) => void DropzoneFilesChangeDetails Runs when selected files change for Dropzone. runtime Marks the Root part so Starwind Runtime can find it. data-disabled prop Reflects the disabled prop on the Root part. data-drag-active state Reflects the drag active state on the Root part. data-has-files Reflects the has files state on the Root part. data-is-uploading Reflects the uploading prop on the Root part. uploading getUploading setUploading filesChange starwind:files-change files File[] setDisabled input data-sw-dropzone-input accept string Limits which file types can be selected. multiple Allows multiple Dropzone values to be selected. name Sets the submitted form field name. required Marks the form control as required. Marks the Input part so Starwind Runtime can find it. Reflects the disabled prop on the Input part. uploadIndicator div data-sw-dropzone-upload-indicator Marks the Upload Indicator part so Starwind Runtime can find it. Reflects the uploading state on the Upload Indicator part. loadingIndicator data-sw-dropzone-loading-indicator Marks the Loading Indicator part so Starwind Runtime can find it. Reflects the uploading state on the Loading Indicator part. filesList data-sw-dropzone-files-list Marks the Files List part so Starwind Runtime can find it. Reflects the has files state on the Files List part. Root aria-disabled role tabindex Input type class Upload Indicator Loading Indicator hidden Files List @starwind-ui/astro @starwind-ui/astro/dropzone Render the file input and indicator/list parts statically; runtime owns drag state, keyboard activation, file list rendering, and upload-state synchronization. @starwind-ui/react @starwind-ui/react/dropzone Create the runtime controller once, bridge disabled and uploading changes through setters, and surface file changes through onFilesChange. /docs/components/dropzone/ Direct primitive direct-primitive Styled component Dropzone

Dropzone Primitive

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Input

Props

Data Attributes

Runtime hooks

Metadata

Upload Indicator

Props

State

Data Attributes

Runtime hooks

State

Loading Indicator

Props

State

Data Attributes

Runtime hooks

State

Files List

Data Attributes

Runtime hooks

State

Runtime API

Option Lifecycles

Runtime Setters

Form Participation

Related Styled Components

Changelog

v1.0.0

v0.1.1

v0.1.0