File Input
Choose files in a field that shows their names and ends with an Upload button, and send them with a form.
SVG, PNG or JPG, up to 2 MB.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/file-inputComplete the one-time setup first. Registry JSON lists source files and dependencies.
For this page’s examples, also install:
pnpm dlx shadcn@4.18.0 add @siteplane/formField is installed with Input.
Usage
import { FileInput } from "@/siteplane/components/file-input";
<FileInput accept="image/png,image/svg+xml" aria-label="Company logo" />;Choosing files
The field shows “Choose a file” until a file is chosen, then the file’s name, and the names of several files separated by commas. A click anywhere on the field opens the file dialog. Tab reaches the field’s text and the Upload button, and Enter or Space on either opens the dialog too. Names that are longer than the field end with an ellipsis, and hovering the field shows them in full.
A file input out of sight holds the chosen files. It takes accept, multiple, name, form, required and disabled as a native file input does, so a form around the field sends the files under its name. A file that is picked again is reported again, and a cancelled dialog keeps the files that were chosen before.
Multiple files
multiple lets people choose several files at once. Each pick replaces the files chosen before.
Choose one file or several.
Loading
loading shows a spinner at the end of the field, for example while the chosen file uploads. The field and its button stay usable, so a person can choose another file. onFilesChange receives the files as soon as they are picked, which is where an upload can start.
PDF, up to 10 MB.
In a form
Inside a Field, FieldLabel names the field, FieldDescription and FieldError describe it, and the Field’s name, disabled and invalid reach it. With required, Form checks on submit that a file is chosen, and FieldError explains a missing file. While the field is invalid, the alert icon of an Input Group stands after the names, before the Upload button. On submit, the form data holds the chosen files under the field’s name. Form’s onFormSubmit receives the names that the field shows, so read the files from the form data or from onFilesChange.
Sizes
Omit size to take the provider’s control size. sm is 36 px high, md 40 px, lg 44 px and xl 48 px, as on Input, and the Upload button takes the same size.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
size | sm | md | lg | xl | provider / sm | The control size of the field and its button. |
placeholder | string | "Choose a file" | The text the field shows while no file is chosen. |
button | string | "Upload" | The label of the button at the end of the field. |
accept | string | unset | The file types the dialog offers, as on a native file input. |
multiple | boolean | false | Lets people choose several files at once. |
name | string | unset | The name of the files in the form data. A Field’s name takes precedence. |
form | string | unset | The id of the form the files belong to, for a field outside that form. |
required | boolean | false | A form submits only once a file is chosen. |
disabled | boolean | false | Disables the field and its button. A disabled Field does the same. |
loading | boolean | false | Shows a spinner at the end of the field. |
on | (files: FileList | null) => void | unset | Called with the chosen files after a pick, and with null when a reset of the form empties the field. |
variant | default | soft | default | The surface of the field, as on Input. |
id, aria-label, aria-labelledby, aria-describedby | string | unset | Go to the field’s text, the control that people reach and that a label names. |
aria-invalid | boolean | unset | Marks the field invalid. Inside a Field, set invalid on the Field instead. |
FileInputProps is exported. Other div props, such as className, go to the root, an Input Group with data-slot="file-input". The button carries data-slot="file-input-button". It is a segment of the group, a ghost Button after the field's divider, so it stays flat on the field as the copy action of an Input Group does.
Usage notes
Give the field a label with FieldLabel or aria-label, and name the accepted files in a FieldDescription. accept only filters the dialog, so check the type and the size of each file again where you receive it. The field uploads nothing and shows no preview of a file. To drop files or to show a list of uploads with their progress, use File Upload. For the browser’s own file control, use Input with type="file".