Design

File upload anatomy

The anatomy of file upload component consists of several elements:

Example of the file upload component listing all the different aspect of anatomy.
  1. Label: Labels are headings that identify the purpose or context of the input field. For example, a label might say "First Name" to indicate that the user should enter their first name in the text field. Standard label alignment is left-aligned with the field underneath. Labels are mandatory on all fields with some exceptions such as search fields used in the header.
  2. Required field indicators: To indicate that a field is required, display an asterisk (*) next to the label text and mention at the start of the form that asterisks indicate required fields.
  3. Optional field indicators: Optional field indicators indicate that a field is optional. Clearly indicate optional fields by displaying the word ‘optional’ in parentheses next to the label text.
  4. Hint/Helper text: Helper text conveys additional guidance about the input field, such as how it will be used. It should only take up a single line and be persistently visible.
  5. Drag and drop region: Allows users to interact with the file upload component by dragging items (such as files, images, or text) from one location and dropping them onto the input field. Dragging your mouse anywhere within the bounds of the drop zone (dotted area) with an attached file will enable you to drop it inside of the area and begin to upload.
  6. Trailing icons: This is the icon this is most commonly used to indicate an upload action. It only appears on desktop where the upload field is intentionally larger to facilitate easier drag and drop actions.
  7. Upload heading: This text to describes the two ways a user can interact with the upload files component. On mobile ‘drag and drop files here’  is removed.
  8. File upload description: Descriptions help communicate to the user what file size or format limitations there are. Each limitation should be written on a new line. The three most common are, accepted file formats, maximum size and number of files you can upload. This text should be written in plain language and follow the example within the component with each requirement on a new line.
  9. Select files button: “Select files” is the default text that appears with the file upload button. By click this button a user can browse their system for files to upload.
  10. Uploaded file title: The name of the file that has been uploaded including file type.
  11. File type icon: This icon indicates the type of file that has been uploaded, the region is also used for the loading spinner and file error icon.
  12. File actions: There are a number of actions available to users once they have selected a file for upload.
    • During the upload they can ‘cancel’ the process.
    • After the upload is complete they can ‘Remove’ the file.
    • If there error or glitch during upload they  can ‘retry’ to upload the file.
    • If the file is invalid they can ‘remove’ the file.
  13. Loading spinner: The spinner, is a visual element used in user interfaces to indicate that content is being loaded or processed. It is replaced by the file type icon once the file is uploaded.
  14. File Status information: This area indicates the status of file and when complete also the total file size.
  15. Validation messages: When a file is either valid or invalid ot displays the relevant message and is accompanied by the same icons used in standard form fields.

Research and rationale

This design is based on patterns developed by the myQLD project and existing examples from the Agriculture and NSW design system.

The design tries to maintain visual consistency with the existing Qld government designs, it has only been updated to align more closely to the existing form components and to incorporate best practice as found through a comparative review of other design systems.

The myQLD pattern currently has a more advanced version of the loading state component, which while desirable was deemed out of scope for our initial implementation as it required further research, validation and development as seperate component.

Changes from the existing design where:

  • Added more form upload field states including (invalid, disabled and focus)
  • Dark variants added
  • Simpler and more consistent responsive design
  • Primary icon updated to one more commonly used for upload
  • Dotted lines now only used for drag and drop and loading
  • Valid and invalid file upload states where made more consistent with existing form field designs
  • Existing SWE loading spinner used as an alternative to progress bar as simpler to implement and validate for MVP.

Label for file upload instructions

There was a wide variety of different different design systems communicated the instructions on how to interact with the file upload component. It was important to our team that the language used appropriately communicated the 2 ways to upload – via drag and drop or file selection via search.

We did a comparative review of 11 different examples of the text used to describe how interact with the component. Agricultures  designs systems solution "Drag and drop files here or select files to upload"  was deemed the best solution and most aligned to web writing guidlines.

Select vs browse

In our review of other design systems we found that there were two primary approaches for the label of the button within the component. The  majority used either select files or browse.

We chose to use Select over browse because:

  • ‘Select’ is more action-oriented and straightforward.
  • It implies that users are choosing or picking files from their device.
  • This option may be preferable if we want to emphasise the user's active role in the process, more direct and aligned to the task they need to complete.
  • They know the file they want.

‘Browse’ is a bit more descriptive but not as direct. It suggests that users will be exploring or navigating their file system to find the desired files. This option is more preferable if you want to convey a sense of exploration or showcase options. Ie Browse events.

Error messages

When a specific file cannot be uploaded successfully it will show an error state. Our error messages  were developed from the work done on the myQLD project and guidance provided with the uk.gov design system.

Below is list of errors type and examples of how the messages should be styled.

  • If the file is the wrong file type
    Say ‘The selected file must be a [list of file types]’.
For example, ‘The selected file must be a CSV or ODS’ or ‘The selected file must be a JPG, BMP, PNG, TIF or PDF’.
  • If the file is too big

    Say ‘The selected file must be smaller than [largest file size]’.
For example, ‘The selected file must be smaller than 2MB’.
  • If the file is empty
    Say ‘The selected file is empty’.
  • If the file contains a virus
    Say ‘The selected file contains a virus’.
  • If the file is password protected
    Say ‘The selected file is password protected’.
  • If there was a problem and the file was not uploaded
    Say ‘The selected file could not be uploaded – try again’.
  • If there is a limit on how many files the user can select
    Say ‘You can only select up to [highest number] files at the same time’.
For example, ‘You can only select up to 10 files at the same time’.
  • If duplicate file name detected
    Say 'Filename already in use. Please rename file before trying again.'
  • File has illegal charactersSay ‘Unsupported characters in file name. Only use letters, numbers, space, and special characters -_(’

Last updated: April 2026

Back to top