Components

FileUpload

Headless native file-picker, dropzone, validation, selected-file collection, and removal primitives.

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

• 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.

HiddenInput

Renders the hidden native input type="file", opens through Trigger, and sends selected FileList values into Root validation.

Trigger

Opens HiddenInput's native file picker. It renders a button by default and adds button semantics to non-native custom elements.

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.

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 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

See CHANGELOG.md.