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
-
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> -
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.
export function FileUpload(props: FileUploadProps): JSX.Element
Its props, FileUploadProps. A ? marks one the caller may leave out.
| label | ReactNode | the question, such as "Upload a file" |
| rules | FileRules | required, accept, maxBytes, multiple and maxFiles; accept and multiple go on the input too |
| id? | string | the input's id; React's useId() when left out |
| name? | string | what the files are submitted as; the id when left out |
| hint? | ReactNode | help 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? | boolean | check the files and show the message: after a choice or when the form is submitted |
| error? | ReactNode | an error to show instead, such as "The selected file could not be uploaded – try again" |
| onChange? | (value: readonly FileInfo[]) => void | called with each chosen file's name, size and MIME type, to keep as files |
| onFiles? | (value: unknown) => void | called with the browser's File objects, to upload (to a signed URL from storage.signed-url) |
| onBlur? | () => void | called when the input loses focus |
| disabled? | boolean | shown but not usable |
| className? | string | added to the wrapper's classes |
| renders | JSX.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";
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
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.
-
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> -
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> -
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> -
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> -
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> -
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> -
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> -
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> -
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> -
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
-
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> -
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> -
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
| Path | Bytes |
|---|---|
| NOTICE | 1,220 |
| README.md | 3,020 |
| impl/typescript.tsx | 3,280 |
| vectors.json | 10,595 |