File upload

File upload anatomy

The anatomy of file upload component consists of several elements:

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 -_(’

Classes

Upload field

File status

Setting up the upload constraints

Accepted files

Use the accept and date-file-types props to specify what file types are allowed to be uploaded.

Maximum file size

Use the data-max-size prop to set a maximum size for each file. This value is measured in megabytes (mb).

Number of allowed files

You can also set data-max-files to limit how many files can be selected. Selecting multiple files is also supported with File upload. Simply add multiple="true".

Accessible loading spinner requirements

Keep these considerations in mind if you're modifying the Design System or creating a custom component.

WCAG guidelines

1.4.1 Use of Colour

Use icons alongside error messages so that colour alone isn't used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element (WCAG, 2018).

1.4.3 Contrast (Minimum)

Border colours for the drag and drop region meet a 3:1 minimum colour contrast ratio to the background (WCAG, 2018).

1.3.1, 3.3.2: Indicate Required Fields

Clearly indicate required fields with an asterisk (*) or other visual indicators, and add the required attribute to the text input. Additionally, provide textual information, such as "(required)," for screen reader users (WCAG, 2018).

2.1.1 Keyboard

All functionality of the content, including the file upload drop zone, must be operable through a keyboard interface without requiring specific timings for individual keystrokes.

Users must be able to interact with the drag-and-drop functionality using a keyboard. Navigation to the upload area can be done using the Tab key, and activation (dropping files) should be possible with Enter or Space keys.

2.4.3 Focus Order

Ensure the navigation through components and controls on the web page is logical and intuitive. The sequence of focusing (tabbing) through elements should reflect the visual order and logical flow.

2.5.7 Dragging Movements

Do not use 'drag and drop' as the sole method for uploading files. Provide additional methods, such as a 'Choose file' button, to ensure the functionality is accessible to users who cannot use drag-and-drop due to mobility impairments.

3.3.1, 3.3.3: Implement Accessible Error Messages

If an input error is automatically detected, the item that is in error is identified and the error is described to the user in text. (Level A).

When displaying error messages, ensure they're clear, concise, and accessible to all users. Use the 'aria-describedby' attribute to associate error messages with the corresponding input field (Level AA) (WCAG, 2018).

3.3.2: Provide Clear Instructions

Ensure that any instructions or guidelines for filling out the text input are clear and easily understandable. This helps users avoid mistakes and better understand the expected input format. This is commonly seen in the form of hint text that appears below the labes.

4.1.2 Name, Role, Value

By building on the native HTML <input type="file"> element and enhancing it with additional interactive components like a visual <button>, the implementation needs to maintain accessible name, role, and value properties. These should be properly assigned so that assistive technologies can accurately communicate the controls to users. Ensuring that the button and the entire component are correctly labeled with ARIA attributes enhances the accessibility of the user interface.

Other useful accessibility guidance

Progressive Enhancement

Fallback Mechanisms: Design the file input component as a progressive enhancement of <input type="file" />. If advanced features fail to initialise, the component should still function and appear as a standard file input to ensure basic accessibility and functionality are maintained.

Make your uploaded file reusable if possible.

Make sure users can easily reuse a previously uploaded file within a single journey, unless doing so would be a major security or privacy concern. This is not mandatory but however it does make the experience better for users and comply with WCAG 2.2 success criterion 3.3.7 Redundant Entry.