Skip to content

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" />;
}

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.

Attach one document.

Invoice-01012026.pdf
1.2 MBUploading...
50%
Invoice-01012026.pdf
1.2 MBCompleted
100%
Invoice-01012026.pdf
1.2 MBUpload failed
0%

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:

  • uploading shows the file, a loader with “Uploading…”, and the Loading Outline button.
  • completed (Figma Filled) shows a check with “Completed”, an optional Info badge, the Remove icon button for onRemove, and the View button for onPreview.

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.

Pick a file to see the Uploading and Filled states.

director-sign.png
250 KBUploading...
director-sign.pngRecently added
250 KBCompleted

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.

Invoice-01012026.pdfRecently added
1.2 MBCompleted
100%

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.

Native multiple selection passes the complete FileList to onFilesChange.

No images selected

FileUploadCard maps pdf, doc, xls, and img to Lucide’s FileText, FileType, FileSpreadsheet, and FileImage icons, respectively.

Invoice.pdf
1.2 MBCompleted
100%
Proposal.doc
680 KBCompleted
100%
Budget.xls
240 KBCompleted
100%
Preview.jpg
920 KBCompleted
100%
  • The full dropzone activates a native file input. label provides a visible accessible name. Without it, the input uses the dropzone instruction as its name.
  • description and error associate text with the input. The application checks file size and format and sets error. The default 5 MB helper text does not validate files.
  • onFilesChange receives the native FileList after selection or drop. Native onChange receives picker changes. accept, multiple, name, required, and disabled reach the file input.
  • On browsers that reject assigning dropped files to the native input, onFilesChange still receives them, but native form submission does not include the dropped files. Submit that FileList in the application when using drag and drop.
  • In the sm Uploading 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 named View {fileName} and Remove {fileName}.
  • FileUploadCard shows progress and status supplied by the application. Optional action callbacks render named buttons. The application owns the transfer, retry, cancellation, and preview.
  • NesraI18nProvider translates the dropzone instruction, upload status text, and action labels. See Interface translations for the message keys.
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.

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.