File Upload

When to Use

Use FileUpload when users must choose local files and the interface needs a custom picker, drop target, selected-file list, or client-side feedback. Use a plain input type="file" when the browser control is sufficient. Client checks improve feedback but are not a security boundary; validate every uploaded file again on the server.

Features

The behavior Atom owns before your product adds appearance.

• Supports controlled and uncontrolled file arrays.
• Uses a hidden native file input for picker and form semantics.
• Supports button and drag-and-drop selection.
• Validates accept rules, count, size, and custom errors.
• Appends or replaces multiple-file selections.
• Exposes rejected files, drag state, item metadata, and removal actions.
• Integrates IDs, descriptions, and state with Field.

Import

import { FileUpload } from "@flowstack-ui/atom";

Anatomy

<FileUpload.Root>
  <FileUpload.HiddenInput />
  <FileUpload.Trigger />
  <FileUpload.Dropzone />
  <FileUpload.ItemGroup>
    <FileUpload.Item>
      <FileUpload.ItemName />
      <FileUpload.ItemSize />
      <FileUpload.ItemDeleteTrigger />
    </FileUpload.Item>
  </FileUpload.ItemGroup>
</FileUpload.Root>

fileMatchesAccept()
validateFileUploadFiles()
formatFileSize()

API Reference

Root

Renders a div, owns selection and validation state, and supplies behavior to all parts. Local field-state props override Field context. An uncancelled native form reset restores uncontrolled defaultFiles, clears rejections and drag state, and resets the native file picker.

HiddenInput

Renders the transparent native input type="file", opens through Trigger, and sends selected FileList values into Root validation. It is aligned with Trigger so native required feedback points to the visible control and redirects validation focus there. Accepted drag/drop files are synchronized back to the native input when the browser permits FileList assignment.

Trigger

Opens HiddenInput's native file picker. It renders a button by default and adds button semantics to non-native custom elements. Inside Field, its accessible name combines the Field label with its authored action text, and it receives the Field description/error and invalid state. Explicit native ARIA naming and description props override those defaults.

Dropzone

Renders a div that accepts dropped files. It owns drag events but adds no button role or tab stop; include Trigger when keyboard picker access is needed. Drag state is validated against the same type, count, size, and custom rules as the eventual drop. Root prevents file drops on the surrounding document by default so an accidental outside drop does not replace the current page; preventDocumentDrop={false} opts out without affecting non-file drag/drop.

ItemGroup

Renders a ul for selected files. A function child receives each (file, index); function children cannot be combined with asChild.

Item

Renders one li and provides its resolved File and index to metadata/removal parts. It returns null when neither file nor the requested Root index exists.

ItemName

Renders a span containing the File name by default. Consumer children replace that text; asChild and render are supported.

ItemSize

Renders a span containing formatFileSize(file.size) by default. Consumer children replace the formatted text; asChild and render are supported.

ItemDeleteTrigger

Renders a button that removes the current Item, resets the native input so the same file can be chosen again, and respects disabled/read-only state.

fileMatchesAccept

Returns whether a File matches a comma-separated extension, exact MIME type, or wildcard MIME rule. No rule or an empty rule accepts the file.

validateFileUploadFiles

Returns { acceptedFiles, rejectedFiles }. Rejection errors contain "type", "size", "count", and any nonempty custom validation string.

formatFileSize

Formats bytes with binary-sized B, KB, MB, GB, or TB units and returns "0 B" for non-finite or nonpositive input.

The entry also exports useFileUploadContext and useFileUploadItemContext for advanced custom parts; both require their corresponding parent.

Examples

Multiple Documents

import { FileUpload } from "@flowstack-ui/atom";

export function DocumentUpload() {
  return (
    <FileUpload.Root name="documents" accept=".pdf,.txt" multiple maxFiles={5}>
      <FileUpload.HiddenInput />
      <FileUpload.Trigger>Choose documents</FileUpload.Trigger>
      <FileUpload.Dropzone>Drop PDF or text files here</FileUpload.Dropzone>
      <FileUpload.ItemGroup>
        {(file, index) => (
          <FileUpload.Item key={`${file.name}-${index}`} file={file}>
            <FileUpload.ItemName />
            <FileUpload.ItemSize />
            <FileUpload.ItemDeleteTrigger>Remove</FileUpload.ItemDeleteTrigger>
          </FileUpload.Item>
        )}
      </FileUpload.ItemGroup>
    </FileUpload.Root>
  );
}

Report Rejections

import { useState } from "react";
import { FileUpload, type FileUploadRejectedFile } from "@flowstack-ui/atom";

export function ImageUpload() {
  const [rejected, setRejected] = useState<FileUploadRejectedFile[]>([]);
  return (
    <FileUpload.Root
      accept="image/*"
      maxSize={2 * 1024 * 1024}
      onRejectedFilesChange={setRejected}
    >
      <FileUpload.HiddenInput />
      <FileUpload.Trigger>Choose image</FileUpload.Trigger>
      <p aria-live="polite">
        {rejected.length > 0 ? "The selected image was not accepted." : ""}
      </p>
    </FileUpload.Root>
  );
}

Accessibility

HiddenInput remains an aligned native file control and owns its constraints. A validation attempt is mirrored to Root, Trigger, and Field. Inline behavior suppresses the browser bubble; native behavior keeps it at Trigger's bounds. The visible Trigger carries the Field label, description/error, and invalid relationships while preserving its own action wording. Drag/drop is optional; always include a Trigger for keyboard, touch, and single-pointer selection.

HiddenInput supplies native file-input semantics and must be present for Trigger to open a picker. Give the upload a visible Field.Label or another accessible name. Trigger and ItemDeleteTrigger use button keyboard behavior; Dropzone alone is pointer-only. Announce rejection feedback in visible text and validate file type, size, and content again on the server.

Changelog

Unreleased

0.24.0

• Added source-led Agent Knowledge for native picker and form semantics, dropzone enhancement, validation boundaries, file-list composition, and same-file reselection behavior.

0.19.7

• Related the visible Trigger to its Field label, description/error, required, and invalid state while preserving authored action wording.
• Made Dropzone accept/reject state follow the configured file constraints before drop and added default file-only document-drop protection.

0.6.16

• Explicitly scrolled inline validation-directed focus into view.

0.6.15

• Exposed inline validation-directed focus through [data-focus-visible] until blur.

0.6.13

• Mirrored HiddenInput constraints to the visible upload surface, Field, and Form under the shared inline/native validation contract.

0.6.12

• Aligned the native file input with Trigger for required feedback and synchronized accepted files after picker and drag/drop updates.

0.5.0

• Synchronized uncontrolled files, rejection state, and the native picker with native form reset while preserving Field state and relationships.

0.2.0

• Fixed read-only Trigger, Dropzone, and ItemDeleteTrigger parts so they expose data-readonly instead of only reporting disabled state.

0.1.0

• Initial Atom release.