Component reference
FileUpload
Attach supporting documents to a request.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Width adapts to the available space
"use client";
import { useState } from "react";
import { FileUpload, Button } from "@pimolu/react";
function RequestAttachments() {
const [files, setFiles] = useState<File[]>([]);
return (
<form
className="grid gap-5 min-w-0"
onSubmit={(event) => event.preventDefault()}
>
<FileUpload
label="Project attachments"
description="Brief, references and signed scope. PDF, PNG or JPG, up to 5 MB each."
accept=".pdf,image/png,image/jpeg"
multiple
maxFiles={4}
maxSize={5 * 1024 * 1024}
files={files}
onFilesChange={setFiles}
validateFile={(file) => file.name.toLowerCase().includes("draft")
? "Draft files cannot be submitted."
: null}
/>
<div className="flex flex-wrap items-center gap-3 min-w-0 justify-between">
<span className="text-sm text-muted leading-relaxed">
{
files.length === 0
? "No attachment ready."
: `${files.length} attachment(s) ready.`
}
</span>
<div className="flex flex-wrap items-center gap-3 min-w-0">
<Button
type="button"
appearance="ghost"
size="sm"
disabled={files.length === 0}
onClick={() => setFiles([])}
>
Clear
</Button>
<Button type="submit" size="sm" disabled={files.length === 0}>Submit request</Button>
</div>
</div>
</form>
);
}
export function DemoExample() {
return (<RequestAttachments />);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Image previews
Image files show a local object URL thumbnail; other formats keep the document icon. showPreviews={false} restores the icon-only list.
Uncontrolled
defaultFiles seeds the list; without a files prop the component owns every change and still calls onFilesChange.
States
An external error marks the field invalid; disabled removes the trigger, the input and every remove button from the form.
Usage
Accepted types and size checks improve feedback; validate uploads again on the server.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluFileUploadProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
files | File[] | undefined | — | Controlled list of files. |
defaultFiles | File[] | undefined | an empty list | Initial files when uncontrolled. Defaults to an empty list. |
onFilesChange | ((files: File[]) => void) | undefined | — | Called with the complete next list after a selection or a removal. |
accept | string | undefined | — | Native accept string, for example `"image/*,.pdf"`. Used both by the file input and by the validation of dropped or selected files. |
multiple | boolean | undefined | true | Allow more than one file. Defaults to true. |
maxFiles | number | undefined | — | Maximum number of files kept. Omit for no limit. |
maxSize | number | undefined | — | Maximum size of a single file, in bytes. Omit for no limit. |
disabled | boolean | undefined | false | Disable the trigger, the input and every remove button. |
label | ReactNode | — | Visible label. |
description | ReactNode | — | Supporting text below the label. |
error | ReactNode | — | Error text; also marks the control as invalid. |
validateFile | PimoluFileValidator | undefined | — | Extra per-file validation, applied after accept and maxSize. |
buttonLabel | string | undefined | — | Text of the trigger button. |
emptyText | string | undefined | "No files selected" | Text shown when no file is selected. |
removeFileLabel | ((file: File) => string) | undefined | `Remove <name>` | Accessible name of a remove button. Defaults to `Remove <name>`. |
showPreviews | boolean | undefined | true | Show an image thumbnail for image files. Other files keep the document icon. Defaults to true. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
children | ReactNode | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | Standard React/HTML attribute. |
filesFile[] | undefinedNo default extracted.
Controlled list of files.
defaultFilesFile[] | undefinedDefault: an empty list
Initial files when uncontrolled. Defaults to an empty list.
onFilesChange((files: File[]) => void) | undefinedNo default extracted.
Called with the complete next list after a selection or a removal.
acceptstring | undefinedNo default extracted.
Native accept string, for example `"image/*,.pdf"`. Used both by the file input and by the validation of dropped or selected files.
multipleboolean | undefinedDefault: true
Allow more than one file. Defaults to true.
maxFilesnumber | undefinedNo default extracted.
Maximum number of files kept. Omit for no limit.
maxSizenumber | undefinedNo default extracted.
Maximum size of a single file, in bytes. Omit for no limit.
disabledboolean | undefinedDefault: false
Disable the trigger, the input and every remove button.
labelReactNodeNo default extracted.
Visible label.
descriptionReactNodeNo default extracted.
Supporting text below the label.
errorReactNodeNo default extracted.
Error text; also marks the control as invalid.
validateFilePimoluFileValidator | undefinedNo default extracted.
Extra per-file validation, applied after accept and maxSize.
buttonLabelstring | undefinedNo default extracted.
Text of the trigger button.
emptyTextstring | undefinedDefault: "No files selected"
Text shown when no file is selected.
removeFileLabel((file: File) => string) | undefinedDefault: `Remove <name>`
Accessible name of a remove button. Defaults to `Remove <name>`.
showPreviewsboolean | undefinedDefault: true
Show an image thumbnail for image files. Other files keep the document icon. Defaults to true.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
childrenReactNodeNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLDivElement> | undefinedNo default extracted.
Standard React/HTML attribute.
Accessibility
- Keep a labelled file-input path, clear rejection messages and accessible removal actions.