File Input
⋯
FileInput renders Figma’s File Uploader. Size lg is a 200px high dropzone with the Default,
Focused, Error, and Disabled treatments. Size sm is a 64px row that adds the Uploading and Filled
states. Both keep the native file input for keyboard use and form submission. FileUploadCard
renders the separate Uploading, Completed, and Failed status designs that pair with lg.
import { FileInput } from "@nesra/ui/file-input";
export function AttachmentField() { return <FileInput label="Attachment" name="attachment" accept=".pdf,.jpg,.jpeg,.doc,.xls" />;}Both exports are also available from @nesra/ui.
FileUploadCard displays an upload that the application is already tracking. Pass its status,
progress, and optional action handlers from that upload state:
import { FileUploadCard } from "@nesra/ui/file-input";
export function UploadedAttachment() { return <FileUploadCard fileName="report.pdf" fileSize="2 MB" status="completed" />;}Examples
Section titled “Examples”States and selection
Section titled “States and selection”The dropzone takes the focus ring when its file input has keyboard focus, and the destructive border
and ring when error is set. Disabled renders a stroke-divider border, icon-disabled for the
upload icon, and text-disabled for the copy. Colors follow the
field state colors in Light and Dark.
FileUploadCard draws progress as a gradient from categorical-blue-border to
categorical-blue-base on a categorical-neutral-border track. The file type icon uses
icon-brand-primary, and the action buttons use icon-muted with the focus ring.
import { FileInput, FileUploadCard } from "@nesra/ui/file-input";import { useState } from "react";
export function FileInputBasicExample() { const [fileName, setFileName] = useState("");
return ( <div className="grid w-full max-w-xl gap-nesra-spacing-lg"> <FileInput accept=".pdf,.jpg,.jpeg,.doc,.xls" description={fileName ? `Selected: ${fileName}` : "Attach one document."} name="attachment" onFilesChange={(files) => setFileName(files[0]?.name ?? "")} /> <FileInput error="File is too large or the file format is not supported" /> <FileInput disabled /> <FileUploadCard fileName="Invoice-01012026.pdf" fileSize="1.2 MB" progress={50} status="uploading" /> <FileUploadCard fileName="Invoice-01012026.pdf" fileSize="1.2 MB" status="completed" /> <FileUploadCard fileName="Invoice-01012026.pdf" fileSize="1.2 MB" status="failed" /> </div> );}Size sm
Section titled “Size sm”size="sm" lays the dropzone out as one row: “No file chosen” in Body/Small/Medium text-headline,
the helper text in Body/XSmall/Regular text-support, and the Outline sm Upload button. The row
is 64px high with 16px horizontal padding (padding-2xl) and a 12px gap (padding-xl).
Focused and Error match lg. Disabled keeps the stroke-border outline, as Figma’s sm Disabled
variant does.
Set status with fileName and fileSize to show an upload in place:
uploadingshows the file, a loader with “Uploading…”, and the Loading Outline button.completed(FigmaFilled) shows a check with “Completed”, an optional Infobadge, the Remove icon button foronRemove, and the View button foronPreview.
While status is set, the row no longer opens the picker or accepts drops. The native input keeps
its files for form submission. onRemove does not clear the native input. Reset it through the ref
if the form submits natively. The application owns the upload and passes each status.
import { FileInput, type FileInputStatus } from "@nesra/ui/file-input";import { useState } from "react";
interface Upload { fileName: string; fileSize: string; status: FileInputStatus;}
export function FileInputSmallExample() { const [upload, setUpload] = useState<Upload | undefined>();
return ( <div className="grid w-full max-w-xl gap-nesra-spacing-lg"> <FileInput {...upload} accept=".jpg,.jpeg,.png" badge="Recently added" description="Pick a file to see the Uploading and Filled states." helperText="Maximum 5 MB file size (JPG, PNG)" label="Signature" name="signature" onFilesChange={(files) => { const file = files[0]; if (!file) return; const fileSize = `${Math.max(1, Math.round(file.size / 1024))} KB`; setUpload({ fileName: file.name, fileSize, status: "uploading" }); // Replace the timer with the application's upload request. window.setTimeout( () => setUpload({ fileName: file.name, fileSize, status: "completed" }), 1500, ); }} onPreview={() => { // Open the file in the application's viewer. }} onRemove={() => setUpload(undefined)} size="sm" /> <FileInput error="File format is not supported" helperText="Maximum 5 MB file size (JPG, PNG)" label="Company logo" size="sm" /> <FileInput disabled helperText="Maximum 5 MB file size (JPG, PNG)" label="Stamp" size="sm" /> <FileInput fileName="director-sign.png" fileSize="250 KB" label="Uploading" size="sm" status="uploading" /> <FileInput badge="Recently added" fileName="director-sign.png" fileSize="250 KB" label="Filled" onPreview={() => {}} onRemove={() => {}} size="sm" status="completed" /> </div> );}Completed badge
Section titled “Completed badge”badge renders Figma’s Info Soft 20px Badge after the file name, such as “Recently added”. It
appears only when status is completed, on both FileUploadCard and the sm FileInput.
import { FileUploadCard } from "@nesra/ui/file-input";
export function FileUploadCardBadgeExample() { return ( <FileUploadCard badge="Recently added" fileName="Invoice-01012026.pdf" fileSize="1.2 MB" onPreview={() => {}} onRemove={() => {}} status="completed" /> );}Validate selected files
Section titled “Validate selected files”accept suggests file types in the native picker. It does not validate dropped files. Check the
FileList from onFilesChange against the application’s size and type policy, then set error
when a file fails.
import { FileInput } from "@nesra/ui/file-input";import { useState } from "react";
const maxBytes = 5 * 1024 * 1024;const allowedTypes = new Set(["application/pdf", "image/jpeg"]);
export function FileInputValidationExample() { const [fileName, setFileName] = useState(""); const [error, setError] = useState("");
function handleFiles(files: FileList) { const file = files[0]; if (!file) return; if (file.size > maxBytes || !allowedTypes.has(file.type)) { setFileName(""); setError("Choose a PDF or JPG under 5 MB."); return; } setError(""); setFileName(file.name); }
return ( <div className="grid w-full max-w-xl gap-nesra-spacing-sm"> <FileInput accept=".pdf,.jpg,.jpeg" aria-label="Upload a PDF or JPG" error={error} helperText="PDF or JPG, up to 5 MB" onFilesChange={handleFiles} /> {fileName && <output>Ready to upload: {fileName}</output>} </div> );}Multiple files
Section titled “Multiple files”Native multiple selection passes the complete FileList to onFilesChange.
import { FileInput } from "@nesra/ui/file-input";import { useState } from "react";
export function FileInputMultipleExample() { const [names, setNames] = useState<string[]>([]);
return ( <div className="grid w-full max-w-xl gap-nesra-spacing-md"> <FileInput accept="image/*" aria-label="Upload images" helperText="Choose or drop multiple images" multiple onFilesChange={(files) => setNames(Array.from(files, (file) => file.name))} /> <output className="type-nesra-body-small-regular text-nesra-text-support"> {names.length ? names.join(", ") : "No images selected"} </output> </div> );}File type icons
Section titled “File type icons”FileUploadCard maps pdf, doc, xls, and img to Lucide’s FileText, FileType,
FileSpreadsheet, and FileImage icons, respectively.
import { FileUploadCard } from "@nesra/ui/file-input";
export function FileInputFileTypesExample() { return ( <div className="grid w-full max-w-xl gap-nesra-spacing-md"> <FileUploadCard fileName="Invoice.pdf" fileSize="1.2 MB" fileType="pdf" status="completed" /> <FileUploadCard fileName="Proposal.doc" fileSize="680 KB" fileType="doc" status="completed" /> <FileUploadCard fileName="Budget.xls" fileSize="240 KB" fileType="xls" status="completed" /> <FileUploadCard fileName="Preview.jpg" fileSize="920 KB" fileType="img" status="completed" /> </div> );}Accessibility
Section titled “Accessibility”- The full dropzone activates a native file input.
labelprovides a visible accessible name. Without it, the input uses the dropzone instruction as its name. descriptionanderrorassociate text with the input. The application checks file size and format and setserror. The default 5 MB helper text does not validate files.onFilesChangereceives the nativeFileListafter selection or drop. NativeonChangereceives picker changes.accept,multiple,name,required, anddisabledreach the file input.- On browsers that reject assigning dropped files to the native input,
onFilesChangestill receives them, but native form submission does not include the dropped files. Submit thatFileListin the application when using drag and drop. - In the
smUploading and Filled states, the status text is an<output>. The loading button is hidden from assistive technology because the status already says “Uploading…”. View and Remove are namedView {fileName}andRemove {fileName}. FileUploadCardshows progress and status supplied by the application. Optional action callbacks render named buttons. The application owns the transfer, retry, cancellation, and preview.NesraI18nProvidertranslates the dropzone instruction, upload status text, and action labels. See Interface translations for the message keys.
API reference
Section titled “API reference”FileInput
Section titled “FileInput”| Prop | Type | Default | Effect |
|---|---|---|---|
label |
ReactNode |
— | Adds a visible Base UI Field label. |
description |
ReactNode |
— | Adds help text below the uploader. |
error |
FieldError |
— | Displays an associated validation message. |
helperText |
ReactNode |
Maximum 5 MB file size (PDF, JPG, DOC, XLS) |
Changes the inner helper text. |
onFilesChange |
(files: FileList) => void |
— | Reports picked or dropped files. |
size |
"lg" | "sm" |
"lg" |
200px dropzone, or the 64px row. |
status |
"uploading" | "completed" |
— | sm only. Shows the file in place. |
fileName |
string |
— | sm with status. Visible file name. |
fileSize |
string |
— | sm with status. File size text. |
badge |
ReactNode |
— | sm when completed. Info badge label. |
onPreview |
() => void |
— | sm when completed. Shows View. |
onRemove |
() => void |
— | sm when completed. Shows Remove. |
FileInput accepts native file input props except type, value, defaultValue,
onValueChange, children, and the native size. lg ignores status and its file props. Pair it
with FileUploadCard instead. Its ref points to the native file input. See the
FieldError type for validation matching.
FileUploadCard
Section titled “FileUploadCard”The card accepts native div props. Upload state and actions are supplied by the application.
| Prop | Type | Default | Effect |
|---|---|---|---|
fileName |
string |
required | Names the file and any action buttons. |
fileSize |
string |
required | Displays file size text. |
fileType |
"pdf" | "doc" | "xls" | "img" |
"pdf" |
Chooses the matching Lucide file icon. |
status |
"uploading" | "completed" | "failed" |
required | Chooses status text and available actions. |
progress |
number |
100 when completed, 0 otherwise |
Sets progress, clamped to 0–100. |
onCancel |
() => void |
— | Shows and handles Cancel while not completed. |
onPreview |
() => void |
— | Shows and handles Preview when completed. |
onRemove |
() => void |
— | Shows and handles Remove when completed. |
badge |
ReactNode |
— | Info badge label after the name when completed. |
Figma does not define a hover style for the sm row, a Cancel action while sm is uploading, or a
Failed state for sm. The code adds none of them. Use error for a failed sm upload.
The visual values come from the color roles, typography roles, layout scale, and shape and elevation tokens.