--- title: FileInput description: Choose a file, or drop it. --- > LoamUI documentation, generated from the same source as the live page — > treat it as authoritative for `@loamui/core`. # FileInput A file picker on the native file input: the box is its label, dropping a file is an enhancement, and the choice is announced. ## Import ```tsx import { Field, FileInput } from "@loamui/core"; ``` ## Usage ### One file Inside a Field the control reads its id from the field, so Field.Label and the Prompt both label the input. Click the box or press Enter on the input to open the picker; a file dropped on the box lands in the same input. ```tsx Passport scan PDF or PNG, up to 5 MB Choose a file or drop it here ``` ### Several files multiple forwards to the native input: the picker allows a selection and a drop keeps every file. Without it a drop of several files keeps the first, as the picker would. Say in the prompt that more than one is welcome. ```tsx Supporting documents PDF or PNG, up to 5 MB each Choose files or drop them here ``` ### While a file is held over it The Root carries data-dragging while a drag with files is over the box, and the box answers with the primary line and a tinted surface; under forced colours it takes the system Highlight. The attribute is set by hand here so the state can be seen without a file in hand. ```tsx Passport scan PDF or PNG, up to 5 MB Choose a file or drop it here ``` ### With a size limit The browser enforces neither a size limit nor, for a dropped file, the accept list, so the limit is stated in the description and checked when the form is submitted. A Field.Error before the control marks it invalid and is announced; the message answers in the words of the question. ```tsx Passport scan PDF or PNG, up to 5 MB Choose a file smaller than 5 MB Choose a file or drop it here ``` ## When to use it - When the answer to a question is a file the user already has: a scan of a document, a photo, a spreadsheet to import. - Inside a Field.Root, so the label, the format-and-size description and any error are wired to the control by construction. See the Field page. ## When not to - For a photo the user is expected to take now: the native picker on a phone already offers the camera, so keep the plain control rather than building a capture flow. - For a large or long-running upload that needs progress and cancel: FileInput selects files; the application owns the transfer. Pair it with Progress, or hand the transfer to a dedicated uploader once the file is chosen. ## How it works ### The input is the control, the box is its label There is no button pretending to be a file picker. The native input stays in the page, focusable and named, and the Prompt is a real label for it, so clicking anywhere on the box opens the picker and Tab reaches the input inside it. With scripting the native control is hidden from sight only; without it, the control shows in full with the browser's own file-name display. ### Dropping is an enhancement Dragging a file over the Root marks it (data-dragging) and dropping assigns the files to the same input, then fires change, so nothing downstream can tell a drop from a pick: the form submits the file, onChange runs, the list fills. A drag that carries no files is ignored, and a single-file control keeps the first file dropped, as its picker would. ### The list is the announcement Files is a polite live region that is in the page before any choice is made, so when it fills the choice is read out ("passport.png, 12 kB") as well as shown, whether it came from the picker or a drop. A form reset empties it. It is a list, not a status line, so several files are read as several items. ## Accessibility - Renders a real : the picker, the keyboard behaviour and the platform's own file-name display come from the browser, before and without JavaScript. - The Prompt is a