Skip to main content
Primitives

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

How inline scripts work

API reference

FileUpload.Root

PropType
noFileChosenText

Shown while no file is chosen. Defaults to "No file chosen".

string
multipleFilesChosenText

Shown when more than one file is chosen. %{count} is the number. Defaults to "%{count} files chosen".

Translation
enteredDropZoneAnnouncement

Announced when the user drags files into the drop zone. Defaults to "Entered drop zone".

string
leftDropZoneAnnouncement

Announced when the user drags files out of the drop zone. Defaults to "Left drop zone".

string
emptyClass

Classes for the button while no file is chosen.

string
draggingClass

Classes for the button while files are dragged over the drop zone.

string
disabledClass

Classes for the drop zone while the input is disabled.

string

FileUpload.Announcements

Announces entering and leaving the drop zone. Make it visually hidden.

PropType
asChild

Render 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.

PropType
asChild

Render 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.

PropType
asChild

Render 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.

PropType
asChild

Render 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.

PropType
asChild

Render 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.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean