# 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
### Astro
Use the Astro primitive adapter to render Dropzone anatomy with the Runtime wiring included.
```astro
---
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>
```

### React
Use the React primitive adapter when Dropzone state participates in React rendering.
```tsx
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>
  );
}
```

### HTML
Render the Dropzone data-sw-* contract yourself, then initialize createDropzone.
```html
<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>
```

### Vue
Use the Vue 3.5 beta adapter to render Dropzone anatomy.
```vue
<script setup lang="ts">
import Dropzone from "@starwind-ui/vue/dropzone";
</script>

<template>
  <Dropzone.Root>
    <Dropzone.Input />
    <Dropzone.UploadIndicator>Drop files here</Dropzone.UploadIndicator>
    <Dropzone.LoadingIndicator>Uploading...</Dropzone.LoadingIndicator>
    <Dropzone.FilesList />
  </Dropzone.Root>
</template>
```
## API Reference
### Root
The main element that owns the Dropzone Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `label` |
| Discovery hook | `data-sw-dropzone` |
| Role | `button` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| isUploading | `boolean` | false | control | Controls whether Dropzone is uploading. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
| onFilesChange | `(files: File[], details: DropzoneFilesChangeDetails) => void` | - | callback | Runs when selected files change for Dropzone. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-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` | state | - | Reflects the has files state on the Root part. |
| `data-is-uploading` | prop | - | Reflects the uploading prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| uploading | `boolean` | isUploading | - | `data-is-uploading` | `getUploading` | `setUploading` | Tracks whether Dropzone is uploading files. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| filesChange | onFilesChange | starwind:files-change | files: `File[]` | DropzoneFilesChangeDetails | - | - | Fires when selected files change for Dropzone. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setDisabled` | prop: disabled | - | No | Updates whether Dropzone is disabled from Runtime code. |
| `setUploading` | prop: isUploading | - | No | Updates whether Dropzone is uploading files from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone`, `data-disabled`, `data-drag-active`, `data-has-files`, `data-is-uploading`, `aria-disabled`, `role`, `tabindex` | The visible drop target needs button semantics, disabled state, drag state, file presence, and upload state before hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | accept, multiple, name, required |
| Hidden input | input (file) |

### Input
The native input synchronized by Dropzone.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-dropzone-input` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| accept | `string` | - | attribute | Limits which file types can be selected. | - |
| multiple | `boolean` | - | attribute | Allows multiple Dropzone values to be selected. | - |
| name | `string` | - | attribute | Sets the submitted form field name. | - |
| required | `boolean` | - | attribute | Marks the form control as required. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dropzone-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Input part. |
#### Refs
| Part | Public |
| --- | --- |
| input | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone-input`, `type`, `tabindex`, `class`, `data-disabled`, `disabled` | The native file input must be present for form compatibility while remaining visually hidden and out of the tab order. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | accept, multiple, name, required |
| Hidden input | input (file) |

### Upload Indicator
Upload progress indicator shown by Dropzone.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-dropzone-upload-indicator` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| isUploading | `boolean` | false | control | Controls whether Dropzone is uploading. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dropzone-upload-indicator` | runtime | - | Marks the Upload Indicator part so Starwind Runtime can find it. |
| `data-is-uploading` | state | - | Reflects the uploading state on the Upload Indicator part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| uploading | `boolean` | isUploading | - | `data-is-uploading` | `getUploading` | `setUploading` | Tracks whether Dropzone is uploading files. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| uploadIndicator | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone-upload-indicator`, `data-is-uploading` | The upload indicator reflects the initial uploading state before the runtime attaches. |

### Loading Indicator
Loading indicator shown by Dropzone.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-dropzone-loading-indicator` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| isUploading | `boolean` | false | control | Controls whether Dropzone is uploading. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dropzone-loading-indicator` | runtime | - | Marks the Loading Indicator part so Starwind Runtime can find it. |
| `data-is-uploading` | state | - | Reflects the uploading state on the Loading Indicator part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| uploading | `boolean` | isUploading | - | `data-is-uploading` | `getUploading` | `setUploading` | Tracks whether Dropzone is uploading files. | **React:** Use isUploading for controlled state.<br>**Astro:** Use isUploading for initial state and call setUploading for later updates.<br>**Runtime / HTML:** Use data-is-uploading for initial state and call setUploading for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| loadingIndicator | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone-loading-indicator`, `data-is-uploading`, `hidden` | The loading indicator starts hidden unless the dropzone is already uploading. |

### Files List
Lists the selected files for Dropzone.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-dropzone-files-list` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dropzone-files-list` | runtime | - | Marks the Files List part so Starwind Runtime can find it. |
| `data-has-files` | state | - | Reflects the has files state on the Files List part. |
#### Refs
| Part | Public |
| --- | --- |
| filesList | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dropzone-files-list`, `data-has-files` | The files list starts empty and receives file presence state from the runtime. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createDropzone`](/docs/runtime/#create-dropzone) |
| Import | `@starwind-ui/runtime/dropzone` |
| Root part | root |
| Option props | disabled, isUploading, onFilesChange |
| Option lifecycles | disabled: setter-backed, isUploading: setter-backed, onFilesChange: constructor-only |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | accept, multiple, name, required |
| Hidden input | input (file) |
| Field integration | No |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Dropzone](/docs/components/dropzone/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/dropzone` | `createDropzone` |
| Astro Primitive | `@starwind-ui/astro/dropzone` | `Dropzone`, `DropzoneRoot`, `DropzoneInput`, `DropzoneUploadIndicator`, `DropzoneLoadingIndicator`, `DropzoneFilesList` |
| React Primitive | `@starwind-ui/react/dropzone` | `Dropzone`, `DropzoneRoot`, `DropzoneInput`, `DropzoneUploadIndicator`, `DropzoneLoadingIndicator`, `DropzoneFilesList` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Dropzone` |
| runtime-factory | `createDropzone` |
| part | `Dropzone.Root` |
| part | `Dropzone.Input` |
| part | `Dropzone.UploadIndicator` |
| part | `Dropzone.LoadingIndicator` |
| part | `Dropzone.FilesList` |
## Changelog
### 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.