FileUpload

File selection

Choose files through the visible button, drop them onto the area, or focus the drop area and paste files. All paths share validation. The example stores selected files locally and uses Ready locally in its queue.

<FileUpload
  label="Equipment import"
  description="Choose a CSV up to 1 MiB."
  accept={[".csv", "text/csv"]}
  maxFileSizeBytes={1048576}
  onFiles={selectFiles}
  onReject={reportIssues}
/>

onFiles receives the accepted readonly File[] in input order. A mixed selection can invoke both callbacks; the component also displays every rejection. An empty accepted set or canceled chooser does not call onFiles. Choosing the same file again remains possible. File selection alone does not establish upload or service acceptance.

Constraints and errors

• accept uses case-insensitive extensions such as .csv, MIME types such as text/csv, or MIME wildcards such as image/*. Entries match with OR; an empty list accepts any file type. Extensions work when the browser supplies an empty MIME type.
• multiple defaults to false. maxFiles is a positive integer limit for each selection batch; single-file mode still permits only one file. Successfully read files consume slots in input order, including files rejected by type or size. This does not impose a limit on a caller's existing queue.
• maxFileSizeBytes is an inclusive nonnegative integer. Zero permits empty files. Omitting a limit leaves that dimension unrestricted.
• Invalid constraint configuration is shown and blocks selection. Directories and non-file drops are rejected explicitly.

Each FileRejection has name, code (type, size, count, directory, unsupported, or read) and a readable message. Match on code: the message is for people, and in a size rejection ("File exceeds 1048576 bytes.") the limit is joined to "bytes" by a no-break space so the two never part at a line end. Browser MIME types and chooser filters are hints; the application must parse or inspect content and its service must enforce its own requirements.

Asynchronous drop reads retain input order and report individual failures. Unmounting, disabling the control, changing constraints, or making a newer selection invalidates an older unresolved batch. The caller owns any later content reads, queue identity, permission checks and transport.

Props

The forwarded ref targets the root div. Native div attributes are supported. The visible label and optional description name and describe the group; supplied aria-labelledby and aria-describedby references are appended. Children are internal to the control.

Accessibility

• React Aria supplies the file chooser's press behavior and accessible drop/paste target.
• The visible Choose files button is available without drag and drop. It remains a native button for keyboard activation.
• Disabled state blocks all paths and retires unresolved input. A disabled or blocked control is not faded as a whole: the drop prompt dims and Choose files shows the standard disabled button look, so the text keeps its contrast. Rejection text remains readable without color.
• Read/selection feedback uses a polite status message; it describes local selection rather than upload completion.
• Token focus indicators and wrapping guidance support keyboard and narrow layouts. A long or unbroken label, description or file name breaks anywhere instead of widening the page.

Manifest entry

<FileUpload label="Equipment import" accept={[".csv"]} maxFileSizeBytes={1048576} onFiles={selectFiles} onReject={reportIssues} />

{
  "description": "Choose, drop or paste files with bounded validation and readable rejection feedback.",
  "props": {
    "label": {
      "type": "string",
      "required": true,
      "description": "Visible name for the file selection group."
    },
    "description": {
      "type": "node",
      "description": "Optional guidance associated with the group."
    },
    "accept": {
      "type": "array",
      "description": "Allowed extensions (.csv), MIME types (text/csv), or MIME wildcards (image/*). Case-insensitive, OR matching. Empty means any type. Browser hints do not validate content."
    },
    "multiple": {
      "type": "boolean",
      "default": false
    },
    "maxFiles": {
      "type": "number",
      "description": "Positive integer limit per selection batch. Single-file mode always permits at most one file. Files are considered in input order, including files rejected by type/size."
    },
    "maxFileSizeBytes": {
      "type": "number",
      "description": "Inclusive nonnegative integer byte limit. Zero allows only empty files. Omitted means unlimited."
    },
    "disabled": {
      "type": "boolean",
      "default": false,
      "description": "Blocks all input paths and invalidates in-flight file resolution."
    },
    "onFiles": {
      "type": "function",
      "required": true,
      "description": "Receives accepted readonly File[] in input order. Selection does not establish upload or persistence. No callback for chooser cancellation or an empty accepted set."
    },
    "onReject": {
      "type": "function",
      "description": "Receives readonly FileRejection[]: name, code (type/size/count/directory/unsupported/read), message. Rejections are also displayed."
    },
    "className": {
      "type": "string"
    }
  },
  "composable_with": [
    "UploadQueue",
    "AttachmentPreview",
    "FormSection"
  ],
  "never_inside": [
    "Button"
  ],
  "example": "<FileUpload label=\"Equipment import\" accept={[\".csv\"]} maxFileSizeBytes={1048576} onFiles={selectFiles} onReject={reportIssues} />"
}