# Dropzone Primitive

Dropzone is a Starwind Runtime primitive in the form-value-control contract family.
## 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>
```
## 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 |
| --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Root part. |
| isUploading | `boolean` | false | control | Controls whether Dropzone is uploading. |
| 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 supports controlled state with the isUploading prop. Runtime/HTML reads initial state from data-is-uploading and updates with setUploading. Astro adapters render initial/default state and report changes through Runtime DOM events. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 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 |
| --- | --- | --- | --- | --- |
| 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 |
| --- | --- | --- | --- | --- |
| isUploading | `boolean` | false | control | Controls whether Dropzone is uploading. |
#### 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 supports controlled state with the isUploading prop. Runtime/HTML reads initial state from data-is-uploading and updates with setUploading. Astro adapters render initial/default state and report changes through Runtime DOM events. |
#### 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 |
| --- | --- | --- | --- | --- |
| isUploading | `boolean` | false | control | Controls whether Dropzone is uploading. |
#### 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 supports controlled state with the isUploading prop. Runtime/HTML reads initial state from data-is-uploading and updates with setUploading. Astro adapters render initial/default state and report changes through Runtime DOM events. |
#### 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` |