Functional Weave
Code in Python

react.form.file-upload

A labelled file upload field: accept, size and how-many checked by form.file-check, the chosen files listed with errors.

React ^19 · TypeScript only A React component: use it from a TypeScript project with React installed. A client component ("use client").

1.0.0 · published 2026-10-10 by charlie · Anterra

Pinned by 13 tests, run in TypeScript.

What it does

The GOV.UK file upload: a native `<input type="file">` with its label, hint and error message, whose `accept` and `multiple` come from the same `FileRules` that `form.file-check` checks. It is the UI and the checks only; the bytes go straight to object storage with a signed URL from `storage.signed-url` (an integration), so they never pass through your server.

"use client";
import { FileUpload } from "#fune/react.form.file-upload@^1";

const rules = { required: true, accept: ".pdf,image/*", maxBytes: 10 * 1024 * 1024, multiple: true, maxFiles: 5 };
const [files, setFiles] = useState<FileInfo[]>([]);
const [raw, setRaw] = useState<File[]>([]);

<FileUpload id="evidence" label="Upload your evidence" hint="PDF or images, 10MB or smaller, up to 5 files"
  rules={rules} files={files} onChange={setFiles} onFiles={(f) => setRaw(f as File[])} showError={files.length > 0 || submitted} />

// On submit: the server checks the same FileInfo with validateFiles (any language),
// then signs one PUT URL per file (storage.signed-url's signUpload), and the browser
// PUTs each File to its URL.

For example

  1. one PDF, required: accept and required on the input, nothing listed

    <FileUpload
      id="doc"
      label="Upload a file"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
    />

    renders

    <div class="fune-field"><label class="fune-label" for="doc">Upload a file</label><input class="fune-file-upload" id="doc" type="file" accept=".pdf" required="" name="doc"/></div>
  2. a hint describes the input

    <FileUpload
      id="doc"
      label="Upload your passport"
      hint="PDF, 2MB or smaller"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
    />

    renders

    <div class="fune-field"><label class="fune-label" for="doc">Upload your passport</label><div class="fune-hint" id="doc-hint">PDF, 2MB or smaller</div><input class="fune-file-upload" id="doc" type="file" accept=".pdf" required="" aria-describedby="doc-hint" name="doc"/></div>

The function

Written for React ^19, in TypeScript only. A component: it takes its props and renders HTML, which the tests below pin exactly.

A React capability: React ^19 · TypeScript only. This capability has no Python implementation, so it is shown in TypeScript. A Python project cannot use it: fune build stops and names where it was required. Your choice of Python is kept for every other page.

export function FileUpload(props: FileUploadProps): JSX.Element

Its props, FileUploadProps. A ? marks one the caller may leave out.

labelReactNodethe question, such as "Upload a file"
rulesFileRulesrequired, accept, maxBytes, multiple and maxFiles; accept and multiple go on the input too
id?stringthe input's id; React's useId() when left out
name?stringwhat the files are submitted as; the id when left out
hint?ReactNodehelp under the label, such as "PDF or JPG, 10MB or smaller"
files?readonly FileInfo[]the files chosen so far, as onChange gave them: listed under the input and checked
showError?booleancheck the files and show the message: after a choice or when the form is submitted
error?ReactNodean error to show instead, such as "The selected file could not be uploaded – try again"
onChange?(value: readonly FileInfo[]) => voidcalled with each chosen file's name, size and MIME type, to keep as files
onFiles?(value: unknown) => voidcalled with the browser's File objects, to upload (to a signed URL from storage.signed-url)
onBlur?() => voidcalled when the input loses focus
disabled?booleanshown but not usable
className?stringadded to the wrapper's classes
rendersJSX.Element

The type it declares, generated into your project

/** Choose one file or several; the upload itself is the app's (storage.signed-url). */
export interface FileUploadProps {
  /** the question, such as "Upload a file" */
  readonly label: ReactNode;
  /** required, accept, maxBytes, multiple and maxFiles; accept and multiple go on the input too */
  readonly rules: FileRules;
  /** the input's id; React's useId() when left out */
  readonly id?: string;
  /** what the files are submitted as; the id when left out */
  readonly name?: string;
  /** help under the label, such as "PDF or JPG, 10MB or smaller" */
  readonly hint?: ReactNode;
  /** the files chosen so far, as onChange gave them: listed under the input and checked */
  readonly files?: readonly FileInfo[];
  /** check the files and show the message: after a choice or when the form is submitted */
  readonly showError?: boolean;
  /** an error to show instead, such as "The selected file could not be uploaded – try again" */
  readonly error?: ReactNode;
  /** called with each chosen file's name, size and MIME type, to keep as files */
  readonly onChange?: (value: readonly FileInfo[]) => void;
  /** called with the browser's File objects, to upload (to a signed URL from storage.signed-url) */
  readonly onFiles?: (value: unknown) => void;
  /** called when the input loses focus */
  readonly onBlur?: () => void;
  /** shown but not usable */
  readonly disabled?: boolean;
  /** added to the wrapper's classes */
  readonly className?: string;
}

Your code names it in one line, in the file that uses it

import { FileUpload } from "#fune/react.form.file-upload@^1";
impl/typescript.tsx · 68 lines · open · raw

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

"use client";

import { useId, type JSX, type ReactNode } from "react";
import { formatFileSize, validateFiles, type FileInfo } from "./form_file_check.ts";  ← from form.file-check ^1.0.0 · built alongside by fune
import { FormField, fieldIds } from "./react_form_form_field.ts";  ← from react.form.form-field ^1.0.0 · built alongside by fune
import type { FileUploadProps } from "./react_form_file_upload_types.ts";

function present(node: ReactNode): boolean {
  return node !== null && node !== undefined && node !== false && node !== "";
}

/**
 * The GOV.UK file upload: a label, hint and error message tied to a native
 * file input, whose accept and multiple come from the same FileRules that
 * validateFiles checks, in the browser and again on the server. A file input
 * cannot be controlled, so the app keeps what onChange reports and passes it
 * back as files: they are listed under the input with their sizes, each one
 * in error marked and its message beside it. The bytes go straight to storage
 * with a signed URL (storage.signed-url): onFiles hands over the File objects
 * for that, and this component never reads them.
 */
export function FileUpload(props: FileUploadProps): JSX.Element {
  const auto = useId();
  const { label, rules, hint, files, showError, error, onChange, onFiles, onBlur, disabled, className } = props;
  const id = props.id ?? auto;
  const chosen: readonly FileInfo[] = files ?? [];
  // Checked on every render, so a bad rule fails loudly at once.
  const check = validateFiles(chosen, rules);
  const checking = !present(error) && showError === true;
  const shown: ReactNode = present(error) ? error : checking && !check.valid ? check.message : null;
  const ids = fieldIds(id, present(hint), present(shown));
  const fileError = (index: number) => (checking ? check.errors.find((e) => e.index === index) : undefined);
  return (
    <FormField id={id} label={label} hint={hint} error={shown} className={className}>
      <input
        className={ids.error ? "fune-file-upload fune-file-upload--error" : "fune-file-upload"}
        id={ids.control}
        name={props.name ?? id}
        type="file"
        accept={rules.accept || undefined}
        multiple={rules.multiple || undefined}
        required={rules.required || undefined}
        disabled={disabled}
        aria-describedby={ids.describedBy ?? undefined}
        aria-invalid={ids.error ? true : undefined}
        onChange={(event) => {
          const list = Array.from(event.target.files ?? []);
          onChange?.(list.map((f) => ({ name: f.name, size: f.size, mimeType: f.type })));
          onFiles?.(list);
        }}
        onBlur={onBlur ? () => onBlur() : undefined}
      />
      {chosen.length > 0 ? (
        <ul className="fune-file-list" id={`${id}-files`} aria-live="polite">
          {chosen.map((file, index) => {
            const problem = fileError(index);
            return (
              <li className={problem ? "fune-file-list-item fune-file-list-item--error" : "fune-file-list-item"} key={`${index}-${file.name}`}>
                <span className="fune-file-name">{file.name}</span> <span className="fune-file-size">{formatFileSize(file.size)}</span>
                {problem ? <span className="fune-file-error">{problem.message}</span> : null}
              </li>
            );
          })}
        </ul>
      ) : null}
    </FormField>
  );
}

Install

npm install react react-dom
fune build

With that line in your source, in a TypeScript project (language typescript in fune.project) with React ^19 installed (Functional Weave does not ship it, and fune build stops with the npm install line if it is missing), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add react.form.file-upload
Download for TypeScript react.form.file-upload-1.0.0-typescript.fune · 23,807 bytes sha256 99f9408bb802cd9633e7aff8f9f3d360916642d47e82d570805ab007d898c721

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./react.form.file-upload-1.0.0-typescript.fune, or fetch it from a terminal with fune pull react.form.file-upload@1.0.0:typescript.

It is React ^19 · TypeScript only, so there is no package for Python or Rust. The full package is one file too: react.form.file-upload-1.0.0.fune, 23,779 bytes, sha256 8a034fe98a1d3950a2a42ef1c9aa80e990d7cbc93e1feda64f404324e38d032f.

Customise it in your app

The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.

before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.

// fune: before react.form.file-upload

after — your function gets the result and the arguments, and returns the final result.

// fune: after react.form.file-upload

replace — inside this capability’s code only, calls to a dependency go to your function, with the same signature. Other capabilities that use it are unaffected; write in * to replace it everywhere.

// fune: replace form.file-check in react.form.file-upload
// fune: replace react.form.form-field in react.form.file-upload

step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show react.form.file-upload --steps.

// fune: step react.form.file-upload after <n|label>

Tests

A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript alone, with the React in tooling/react, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json. A component’s tests are render tests: the props go in, and the HTML renderToStaticMarkup makes of them has to match exactly; a React warning during the render fails the test.

  1. one PDF, required: accept and required on the input, nothing listed

    <FileUpload
      id="doc"
      label="Upload a file"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
    />

    renders

    <div class="fune-field"><label class="fune-label" for="doc">Upload a file</label><input class="fune-file-upload" id="doc" type="file" accept=".pdf" required="" name="doc"/></div>
  2. a hint describes the input

    <FileUpload
      id="doc"
      label="Upload your passport"
      hint="PDF, 2MB or smaller"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
    />

    renders

    <div class="fune-field"><label class="fune-label" for="doc">Upload your passport</label><div class="fune-hint" id="doc-hint">PDF, 2MB or smaller</div><input class="fune-file-upload" id="doc" type="file" accept=".pdf" required="" aria-describedby="doc-hint" name="doc"/></div>
  3. any file, optional: no accept, no required

    <FileUpload
      id="any"
      label="Attachment"
      rules={{"required":false,"accept":null,"maxBytes":null,"multiple":false,"maxFiles":null}}
    />

    renders

    <div class="fune-field"><label class="fune-label" for="any">Attachment</label><input class="fune-file-upload" id="any" type="file" name="any"/></div>
  4. a chosen file is listed with its size, no check until showError

    <FileUpload
      id="doc"
      label="Upload a file"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
      files={[{"name":"passport.pdf","size":1572864,"mimeType":"application/pdf"}]}
    />

    renders

    <div class="fune-field"><label class="fune-label" for="doc">Upload a file</label><input class="fune-file-upload" id="doc" type="file" accept=".pdf" required="" name="doc"/><ul class="fune-file-list" id="doc-files" aria-live="polite"><li class="fune-file-list-item"><span class="fune-file-name">passport.pdf</span> <span class="fune-file-size">1.5MB</span></li></ul></div>
  5. nothing chosen and showError: Select a file, input invalid and described

    <FileUpload
      id="doc"
      label="Upload a file"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
      showError
    />

    renders

    <div class="fune-field fune-field--error"><label class="fune-label" for="doc">Upload a file</label><p class="fune-error-message" id="doc-error"><span class="fune-visually-hidden">Error:</span> Select a file</p><input class="fune-file-upload fune-file-upload--error" id="doc" type="file" accept=".pdf" required="" aria-describedby="doc-error" aria-invalid="true" name="doc"/></div>
  6. a file of the wrong type: the field and the file are in error

    <FileUpload
      id="doc"
      label="Upload a file"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
      showError
      files={[{"name":"photo.exe","size":2048,"mimeType":"application/x-msdownload"}]}
    />

    renders

    <div class="fune-field fune-field--error"><label class="fune-label" for="doc">Upload a file</label><p class="fune-error-message" id="doc-error"><span class="fune-visually-hidden">Error:</span> The selected file must be a PDF</p><input class="fune-file-upload fune-file-upload--error" id="doc" type="file" accept=".pdf" required="" aria-describedby="doc-error" aria-invalid="true" name="doc"/><ul class="fune-file-list" id="doc-files" aria-live="polite"><li class="fune-file-list-item fune-file-list-item--error"><span class="fune-file-name">photo.exe</span> <span class="fune-file-size">2KB</span><span class="fune-file-error">The selected file must be a PDF</span></li></ul></div>
  7. a file too large: GOV.UK's size message

    <FileUpload
      id="doc"
      label="Upload a file"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
      showError
      files={[{"name":"scan.pdf","size":3145728,"mimeType":"application/pdf"}]}
    />

    renders

    <div class="fune-field fune-field--error"><label class="fune-label" for="doc">Upload a file</label><p class="fune-error-message" id="doc-error"><span class="fune-visually-hidden">Error:</span> The selected file must be 2MB or smaller</p><input class="fune-file-upload fune-file-upload--error" id="doc" type="file" accept=".pdf" required="" aria-describedby="doc-error" aria-invalid="true" name="doc"/><ul class="fune-file-list" id="doc-files" aria-live="polite"><li class="fune-file-list-item fune-file-list-item--error"><span class="fune-file-name">scan.pdf</span> <span class="fune-file-size">3MB</span><span class="fune-file-error">The selected file must be 2MB or smaller</span></li></ul></div>
  8. a valid file with showError shows no error

    <FileUpload
      id="doc"
      label="Upload a file"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
      showError
      files={[{"name":"scan.pdf","size":1024,"mimeType":"application/pdf"}]}
    />

    renders

    <div class="fune-field"><label class="fune-label" for="doc">Upload a file</label><input class="fune-file-upload" id="doc" type="file" accept=".pdf" required="" name="doc"/><ul class="fune-file-list" id="doc-files" aria-live="polite"><li class="fune-file-list-item"><span class="fune-file-name">scan.pdf</span> <span class="fune-file-size">1KB</span></li></ul></div>
  9. multiple: the input takes several, each file in error names itself

    <FileUpload
      id="ev"
      label="Upload your evidence"
      rules={{"required":false,"accept":".pdf,image/*","maxBytes":10485760,"multiple":true,"maxFiles":3}}
      showError
      files={[{"name":"a.pdf","size":500,"mimeType":"application/pdf"},{"name":"b.docx","size":500,"mimeType":"application/vnd.openxmlformats-officedocument.wordprocessingml.document"},{"name":"c.png","size":0,"mimeType":"image/png"}]}
    />

    renders

    <div class="fune-field fune-field--error"><label class="fune-label" for="ev">Upload your evidence</label><p class="fune-error-message" id="ev-error"><span class="fune-visually-hidden">Error:</span> b.docx must be a PDF or image</p><input class="fune-file-upload fune-file-upload--error" id="ev" type="file" accept=".pdf,image/*" multiple="" aria-describedby="ev-error" aria-invalid="true" name="ev"/><ul class="fune-file-list" id="ev-files" aria-live="polite"><li class="fune-file-list-item"><span class="fune-file-name">a.pdf</span> <span class="fune-file-size">500 bytes</span></li><li class="fune-file-list-item fune-file-list-item--error"><span class="fune-file-name">b.docx</span> <span class="fune-file-size">500 bytes</span><span class="fune-file-error">b.docx must be a PDF or image</span></li><li class="fune-file-list-item fune-file-list-item--error"><span class="fune-file-name">c.png</span> <span class="fune-file-size">0 bytes</span><span class="fune-file-error">c.png is empty</span></li></ul></div>
  10. multiple, too many files: the field's error first

    <FileUpload
      id="ev"
      label="Upload your evidence"
      rules={{"required":false,"accept":".pdf,image/*","maxBytes":10485760,"multiple":true,"maxFiles":3}}
      showError
      files={[{"name":"1.pdf","size":1,"mimeType":"application/pdf"},{"name":"2.pdf","size":1,"mimeType":"application/pdf"},{"name":"3.pdf","size":1,"mimeType":"application/pdf"},{"name":"4.pdf","size":1,"mimeType":"application/pdf"}]}
    />

    renders

    <div class="fune-field fune-field--error"><label class="fune-label" for="ev">Upload your evidence</label><p class="fune-error-message" id="ev-error"><span class="fune-visually-hidden">Error:</span> You can only select up to 3 files</p><input class="fune-file-upload fune-file-upload--error" id="ev" type="file" accept=".pdf,image/*" multiple="" aria-describedby="ev-error" aria-invalid="true" name="ev"/><ul class="fune-file-list" id="ev-files" aria-live="polite"><li class="fune-file-list-item"><span class="fune-file-name">1.pdf</span> <span class="fune-file-size">1 byte</span></li><li class="fune-file-list-item"><span class="fune-file-name">2.pdf</span> <span class="fune-file-size">1 byte</span></li><li class="fune-file-list-item"><span class="fune-file-name">3.pdf</span> <span class="fune-file-size">1 byte</span></li><li class="fune-file-list-item"><span class="fune-file-name">4.pdf</span> <span class="fune-file-size">1 byte</span></li></ul></div>
Show the other 3 tests
  1. an error passed in wins over the check

    <FileUpload
      id="doc"
      label="Upload a file"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
      showError
      error="The selected file could not be uploaded – try again"
      files={[{"name":"scan.pdf","size":1024,"mimeType":"application/pdf"}]}
    />

    renders

    <div class="fune-field fune-field--error"><label class="fune-label" for="doc">Upload a file</label><p class="fune-error-message" id="doc-error"><span class="fune-visually-hidden">Error:</span> The selected file could not be uploaded – try again</p><input class="fune-file-upload fune-file-upload--error" id="doc" type="file" accept=".pdf" required="" aria-describedby="doc-error" aria-invalid="true" name="doc"/><ul class="fune-file-list" id="doc-files" aria-live="polite"><li class="fune-file-list-item"><span class="fune-file-name">scan.pdf</span> <span class="fune-file-size">1KB</span></li></ul></div>
  2. name, disabled and a class of its own

    <FileUpload
      id="doc"
      name="documents"
      label="Upload a file"
      rules={{"required":true,"accept":".pdf","maxBytes":2097152,"multiple":false,"maxFiles":null}}
      disabled
      className="app-upload"
    />

    renders

    <div class="fune-field app-upload"><label class="fune-label" for="doc">Upload a file</label><input class="fune-file-upload" id="doc" type="file" accept=".pdf" required="" disabled="" name="documents"/></div>
  3. a bad rule throws even before a file is chosen

    <FileUpload
      id="doc"
      label="Upload a file"
      rules={{"required":false,"accept":null,"maxBytes":-1,"multiple":false,"maxFiles":null}}
    />

    error: maxBytes

Verification

Verified by the operator, not the sandbox 13 test vectors declared; none run by the registry.

Verified locally by the registry's operator, not by the sandbox. This version was published with FUNE_VERIFY_MODE=inline-dev (the operator's import of the first-party registry, or a development server): the server validated the package - its manifest, signatures, imports, safety lint and test rules - but the registry did not run its test vectors in its sandbox. The operator runs them with `fune verify --all` before importing.

Signed by the registry with key fw-9dc887227da47575 (ed25519), over its integrity and this report's digest. The full report · JSON

More from the author

- **A file input cannot be controlled.** The app keeps what `onChange` reports (each file's name, size and type) and passes it back as `files`: they are listed under the input, with their sizes (`formatFileSize`), and with `showError` each file in error is marked and its message shown beside it. `onFiles` hands over the browser's `File` objects for the upload; this component never reads them. - **Check again on the server.** A file's name, size and type come from the browser and can be anything; `validateFiles` with the same rules on the server (and a size limit on the signed URL) is the real check, and neither says what a file actually contains. - **Messages** are GOV.UK's: "Select a file", "The selected file must be a PDF", "The selected file must be 10MB or smaller", "The selected file is empty"; with several files, each names its file. The field shows the first; `error` shows another (such as "The selected file could not be uploaded – try again"). - **Accessible.** The label's `for`, `aria-describedby` (hint, then error), `aria-invalid` while an error shows, and the list of chosen files is `aria-live="polite"`, so a screen reader hears what was chosen.

It is a client component. Classes: those of `react.form.form-field`, plus `fune-file-upload` (and `fune-file-upload--error`), `fune-file-list`, `fune-file-list-item` (and `fune-file-list-item--error`), `fune-file-name`, `fune-file-size` and `fune-file-error`.

Sources: GOV.UK Design System, "File upload" https://design-system.service.gov.uk/components/file-upload/ ; HTML, the accept attribute https://html.spec.whatwg.org/multipage/input.html#attr-input-accept .

## Notices

Portions derived from GOV.UK Frontend (https://github.com/alphagov/govuk-frontend), Copyright (c) 2017 Crown Copyright (Government Digital Service), under the MIT License; the full notice is in NOTICE.

Files

PathBytes
NOTICE1,220
README.md3,020
impl/typescript.tsx3,280
vectors.json10,595