File upload
A button that opens the file picker, takes dropped files and says which files are chosen.
Used by govuk-react's file upload.
Unstyled
The primitive on plain elements, with no GOV.UK markup or styles: what you start from in your own library.
Code
<>
<label id="file-upload-label" htmlFor="file-upload">
Upload a file
</label>
<FileUpload.Root>
<FileUpload.DropZone>
<FileUpload.Trigger>
<FileUpload.Status />
<FileUpload.Separator className="visually-hidden" />
Choose file or drop file
</FileUpload.Trigger>
<FileUpload.Input id="file-upload" name="file-upload" />
</FileUpload.DropZone>
<FileUpload.Announcements className="visually-hidden" />
</FileUpload.Root>
</>In govuk-react
govuk-react's file upload, built with this primitive.
Code
<FileUploadField
id="file-upload"
name="file-upload"
label="Upload a file"
/>Usage
import * as FileUpload from '@govuk-react/primitives/file-upload';
<label id="photo-label" htmlFor="photo">Upload a photo</label>
<FileUpload.Root>
<FileUpload.DropZone>
<FileUpload.Trigger>
<FileUpload.Status />
<FileUpload.Separator className="visually-hidden" />
Choose file or drop file
</FileUpload.Trigger>
<FileUpload.Input id="photo" name="photo" />
</FileUpload.DropZone>
<FileUpload.Announcements className="visually-hidden" />
</FileUpload.Root>;
Without JavaScript the native file input is shown and the Trigger is hidden. On upgrade the element hides the input and shows the button, which opens the file picker, takes files dropped on it, and says in Status which files are chosen. As in govuk-frontend, the button takes the input’s id (the input’s gets -input added), so the input’s label names it, along with its aria-describedby and disabled. Give the label an id: without one the element adds it, which React warns about when it hydrates. Announcements tells screen readers when files are dragged into and out of the DropZone.
The input’s files are the state, so there is nothing to control. Dropped files fire bubbling input and change events, so React’s onChange hears them. The text is English by default, and multipleFilesChosenText takes a message for each plural form. The button gets data-empty and data-dragging, and the drop zone data-disabled, for styling, or pass class names such as emptyClass.
Inline script
To make the markup interactive before React hydrates, inline @govuk-react/primitives/inline/file-upload-element.js, or render it from React on the server:
import { InlineScript, fileUpload } from '@govuk-react/primitives/inline-script';
<InlineScript script={fileUpload} nonce={nonce} />;API reference
FileUpload.Root
| Prop | Type |
|---|---|
noFileChosenTextShown while no file is chosen. Defaults to "No file chosen". | string |
multipleFilesChosenTextShown when more than one file is chosen. | Translation |
enteredDropZoneAnnouncementAnnounced when the user drags files into the drop zone. Defaults to "Entered drop zone". | string |
leftDropZoneAnnouncementAnnounced when the user drags files out of the drop zone. Defaults to "Left drop zone". | string |
emptyClassClasses for the button while no file is chosen. | string |
draggingClassClasses for the button while files are dragged over the drop zone. | string |
disabledClassClasses for the drop zone while the input is disabled. | string |
FileUpload.Announcements
Announces entering and leaving the drop zone. Make it visually hidden.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |
FileUpload.DropZone
The area that shows files are being dragged over it. Holds the button and the input.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |
FileUpload.Input
The file input, with an id and a label. Shown without JavaScript, and hidden on upgrade.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |
FileUpload.Separator
Between the label and the button's text in the button's accessible name. Defaults to ", ". In Trigger.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |
FileUpload.Status
Which files are chosen: "No file chosen", the file's name, or how many files. In Trigger.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |
FileUpload.Trigger
Opens the file picker, and takes dropped files. Hidden until the element upgrades, when it
takes the input's id, so the input's label names it. Holds Status.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |