Drag-and-drop file uploader

Preview Available in release assets

Enhance an ordinary multipart upload form with bounded drag-and-drop while keeping the native picker and server validation canonical.

Server contract

Use form[enctype=multipart/form-data] with .thin-file-uploader around a native file input. Enhancement never uploads automatically or bypasses form submission.

Users choose files with the native picker and submit the ordinary multipart POST form without JavaScript.

Drag-and-drop file uploader primary example

<form action="/uploads" method="post" enctype="multipart/form-data">
  <div class="thin-file-uploader">
    <label for="documents">Choose documents</label>
    <input class="thin-file-input" id="documents" name="documents" type="file" multiple aria-describedby="upload-guidance upload-errors">
    <small id="upload-guidance">Choose files normally or drop them here when enhancement is available. Maximum 10 MB each.</small>
  </div>
  <div class="thin-error" id="upload-errors" role="status">Server validation appears here.</div>
  <button class="thin-button">Upload documents</button>
</form>

Show code

<form action="/uploads" method="post" enctype="multipart/form-data">
  <div class="thin-file-uploader">
    <label for="documents">Choose documents</label>
    <input class="thin-file-input" id="documents" name="documents" type="file" multiple aria-describedby="upload-guidance upload-errors">
    <small id="upload-guidance">Choose files normally or drop them here when enhancement is available. Maximum 10 MB each.</small>
  </div>
  <div class="thin-error" id="upload-errors" role="status">Server validation appears here.</div>
  <button class="thin-button">Upload documents</button>
</form>

Anatomy

Multipart POST form
Labelled native file input
Drop target enhancement
Persistent constraints
Server error region
Submit button

Variants and sizes

Single file
Multiple files
Picker only

Gallery coverage: No structured variant fixtures are published yet; the primary example above is the only verified production markup.

States and difficult content

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

Idle
Dragging
Files selected
Pending
Progress from server
Success
Server validation error
Oversize rejection
Reconnect
No JavaScript

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

The native picker and submit work normally. Optional behavior only transfers dropped FileList values to the input; Datastar streams server-owned progress and returned validation without inventing success.

Accessibility

Keep the real file input visible and labelled, do not require dragging, state constraints before selection, retain filenames in browser UI, and announce restrained server-confirmed progress and errors.

Contract

POINTER

Basis

Native multipart form and file input; drag/drop is a bounded enhancement, not an APG widget

Evidence

tests/unit/library/file-uploader.test.ts

API

Use form[enctype=multipart/form-data] with .thin-file-uploader around a native file input. Enhancement never uploads automatically or bypasses form submission.

Behavior tier: datastar-required

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

Users choose files with the native picker and submit the ordinary multipart POST form without JavaScript.

Assets and dependencies

/foundation.css
/components.css
/behaviors.js

Dependencies: datastar@1.0.2

Source: packages/ui/src/items/file-uploader/style.ts

Composition

Derived from the examples and style specs, not authored.