File upload

[govuk-design-system]

Description

Help users select and upload a file.

Use this issue to discuss this component in the GOV.UK Design System.

Related link

• Design wiki: Upload a file

[ignaciaorellana]

The HO has a version of this Home Office Design System: Add file

and HMRC has this HMRC Design System: File upload

[quis]

Here’s an example from GOV.UK Notify:

[Emilyallinson]

Hidden quotation marks in CSV files causing uploads to fail

We used the standard file upload component on Look up residency status for relief at source.

We found a particular problem in private beta that we didn’t anticipate. We wanted to share our findings on this, in case other teams want to use the component and come up against the same problem.

When people used Microsoft Excel to create CSVs, this sometimes caused hidden quotation marks to be added to their data. This caused a problem on our back end, because quotation marks are unacceptable characters. This caused the file upload to fail.

A user can resolve this by opening the CSV in a text editor, removing the quotation marks, and re-saving.

We found that once we’d explained this to people, they were able to easily recover from this mistake, and didn’t go on to repeat it. But new users didn’t know what to do.

We added some code to check the files for quotation marks before they’re uploaded, and added a validation message to let them know what the problem is and how to solve it. We also added extra information to a specialist guidance page about uploading CSVs to our service.

We tested a couple of different versions over a couple of sprints, but nothing we tried helped all our users.

To resolve this, we put in some code to programmatically remove the quotation marks. This means that users will never encounter this error again.

[NickColley]

I think there is an opportunity to increase the target size of this component to satisfy WCAG 2.1 Level AAA https://www.w3.org/TR/WCAG21/#target-size

If we were to style it with custom styles it would help this.

[mikeash82]

@gavinwye commented on 31 Jan 2017

#Drag and drop file upload#

Select file - file upload

Other links

GOV.UK elements: http://govuk-elements.herokuapp.com/form-elements/#form-file-upload

@elizabethbartram commented on 3 Feb 2017

@gavinwye commented on 4 May 2017
New screenshots of the employment intermediaries service provided by @stevenaproctor

@jennifer-hodgson commented on 29 Jan 2018
Following our discussions in the working group last week - is file upload (and file download), in fact, a service pattern rather than a pattern?

@adamliptrot-oc commented on 29 Jan 2018
@jennifer-hodgson my view is that if the component parts can be extracted into re-usable patterns, that is fine and those can be documented. There is also a difference in requirements between multiple file upload and single file upload.

@jennifer-hodgson commented on 29 Jan 2018
Thanks for this @adamliptrot-oc. Service patterns are reusable too (they currently exist on a separate backlog, we're discussing how to most usefully house them and make them visible). It seemed to a few of us on the WG call, if I remember correctly, that this was a more complex, multi-step process fulfilling a task which stands as a service pattern. That doesn't preclude, of course, its constituent parts being broken down into useful components and patterns.

@JamesPBoyle commented on 29 Jan 2018
Can I hook you guys into #event-upscan? UpScan is going to replace File-Upload-as-a-Service. We are still in the process of building the service, but it would be useful to make sure the pattern is consistent with the capabilities of the backend system

@adamliptrot-oc commented on 29 Jan 2018
@jennifer-hodgson yep, I raised that, but keen not to rule out the chance for other services to benefit from the findings of a service built purely to handle this type of interaction. Other services look to be finding their own solutions (outside of a service-based one) so it would be useful to find some common ground between them and document a pattern.

@jennifer-hodgson commented on 29 Jan 2018
Thanks for that, @JamesPBoyle, yes that would be useful. I wonder is this also of interest to @benwakefield?

And thanks for your comments also, @adamliptrot-oc. I think you raise an interesting issue about the relationships between components, design patterns and service patterns, and how to organise and display them within the design system in such a way that everyone who needs a certain thing can find it. Perhaps we could discuss this broader issue at the next working group, @stevenaproctor?

@stevenaproctor commented on 29 Jan 2018
@jennifer-hodgson It is definitely something that needs to be discussed, especially because technical reasons may mean a service-design pattern cannot be implemented as designed. Also, there could be conflicting user research from different services.

@lfritzsche commented on 8 Feb

Large file upload with drag and drop and progress bar

@lfritzsche commented on 8 Feb 2018

Description
This pattern allows users to upload large files to HMRC and understand its status, before during and after transfer.

Describe when to use this pattern/component
Is it a pattern or component?
Pattern as it uses a combination of different components
What need does it help you meet?
Allows users to securely send large files to the intended recipient with a record of what happened.
When is it appropriate to use?
When there is a need to send documents to a user where alternatives such as email are not appropriate. Not tested with users who upload lots (e.g. 20+ files daily) of small files

@lfritzsche commented on 8 Feb 2018
How it works
Full description
This upload pattern has been designed to handle the secure transfer of large files from third parties and other government departments to HMRC. It is different to File Upload As A Service (FUUAS) as there are few restrictions on the type and size of files for intended transfer.

Users can send individual files up to the size of 10GB and any format, excluding executable files (.exe). The pattern allows users to select either individual or multiple files at a time via the main CTA or drag and drop. Once the user has selected the files they wish to upload, there is the opportunity for them to remove (if any have been selected in error) or add new files. Basic checks to ensure selected files are not over 10GB individually or .exe format are done in the backend first so that we can provide appropriate erroring. This allows users to correct any issues with file size and also to mitigate files sent in error.

Errors have been dealt with in a unique way and require further testing from an accessibility and usability perspective within Private Beta. Users must fix the issue before they can proceed to upload by removing the file selected with the issue. This allows users to record the file with the issue in case they need to investigate further.

The error box at the top of the screen allows users to remove all files with problems, however this may cause usability issues for users with screen readers as they are unable to link to the individual files. They can then continue to upload, which will then launch the uploading functionality.

Uploads in progress is a new component which uses a progress bar in addition to a percentage indicator with the opportunity to cancel any in flight uploads. If users send files that are larger than average, we found that it was important to give the user more visual feedback for the stats of that upload. A similar erroring pattern is used for files with connection errors as previously described. If any errors occur, the user is still able to proceed with the successful files.

Coded examples
Speak to David Birchall.

Why it works
This pattern works because it is a single page application that gives dynamic inline error messaging when something goes wrong, giving user feedback as to the progress of the upload and individual file control at all stages of the upload process. User research has found that users find this pattern easy to follow with minimal errors encountered.

@lfritzsche commented on 8 Feb 2018

Research on this pattern

SDES has just moved into Private Beta from January 29th 2018. Further research is required to understand how users deal with the transfer of large files (2GB and upwards)

All Alpha research is available in confluence.

Feature specific research summary:
Real time feedback such as error messages and status (failed, cancelled, complete) -
Dynamic components - The upload journey uses a single page which uses JS to dynamically change components based on the scenario. This tested very well with users and they found the additional info, inline errors and individual control very intuitive. Further testing is required for large batches of files uploaded at once.

User control before and during upload - This tested well in alpha, although users didn’t have actual reasons to cancel and retry as they were using dummy files with the prototype. More extensive contextual research is required in Private Beta.

Multi file uploads - Most of our users selected single files to upload. Multi file uploads were useful for those uploading on behalf of their organisation, however within that group only those with a higher technical proficiency used the drag and drop functionality. This is why the design reflects drag and drop as a secondary action.

10GB per individual files - this needs to be extensively tested via contextual enquiry within Private beta. The prototype and the machines we tested on were super efficient and potentially don’t give an accurate reflection of the time it actually takes to upload files. Best practice stipulates around 1GB per file for efficient browser uploading.

[timpaul]

Dropbox Paper audit

The research below was taken from a Dropbox Paper document, which was reviewed and archived on 8 Jan 2019 by the Design System team.

The aim was to reduce the number of places containing guidance and code by:

• migrating relevant, useful content into the Design System itself
• recording important research findings in the community backlog
• removing the original Dropbox Paper page

Research and examples

Report landfill data

Landfill operators have a requirement to report daily, monthly and yearly environmental data. This service allows operators to upload CSV files using either the file browser or drag and drop.

The CSV is subject to a 2-step validation process. The service checks for:

• File errors. (Unsupported file type, incorrect headers, empty file, file too large, file contains a virus)
• Data errors (Users are required to format the files to comply with the landfill data rules)

Formatting errors are identified and grouped and contextual guidance is given which explains how to correct them. The user can delve deeper to identify errors in individual rows and is prompted to fix the errors in their CSV before uploading again.

The pattern has tested well with users of the beta private (9 operators with users of medium to high levels of digital proficiency) and will have more thorough testing in beta live (June’17)

GOV.UK Notify

[sanjaypoyzer]

Not sure if it's worth having a separate issue for Upload a photo of a paper document, but that's what the Blue Badge service has

[edwardhorsford]

Wondering if there's been any progress on having a styled upload button. We used to have one in Elements, but found an accessibility issue with it so removed it with the intention of revisiting when we could look at the accessibility issue.

I find the default button rather easy to miss and not in keeping with our other styles. It would be great if it could be more obvious / possibly adopt the secondary button styles (whatever they become).

[sanjaypoyzer]

@edwardhorsford Are you able to expand on the accessibility issue for the sake of the thread?

[edwardhorsford]

@sanjaypoyzer I think it's covered in this pr to Elements. Skimming the issues noted, I think we could probably do a custom uploader that met the requirements without too much work - this is what passports has.

[adamsilver]

We've recently created a pattern and additional file upload component to the MOJ Design System:

• Upload files pattern: https://moj-design-system.herokuapp.com/patterns/upload-files
• Multi file upload component: https://moj-design-system.herokuapp.com/components/multi-file-upload

Thanks to @amyhupe for helping me write the guidance for this.

[shabana-ali]

I have a couple of issues regarding the File upload component in the design system:

400% zoom field width
At 400% zoom (screenshot on Chrome), the file input does not resize to fit the viewport and horizontal scrolling appears:

Having style width: 100% for the file input does rescale the field but was there a reason for not doing this?

Filename not readout by screen readers
Once a file has been selected from the dialog box (and the box has closed), a screen reader user (tested in JAWS 2020 and NVDA 2020) is not alerted to confirm the filename selected. Also, the filename is not read back to them when re-focusing on the file input field.
Using Chrome's Shadow Dom, it can be seen that aria-hidden="true" is set on this content:

How do we address this?

[36degrees]

@shabana-ali Thanks for flagging these.

Looking at the two issues in turn:

400% zoom field width

Having style width: 100% for the file input does rescale the field but was there a reason for not doing this?

I don't think we'd want to make the file-upload full width, but we might be able to constrain it using max-width.

Would you mind raising a separate issue in the govuk-frontend repo and we can take a look at this for you?

Filename not readout by screen readers
Once a file has been selected from the dialog box (and the box has closed), a screen reader user (tested in JAWS 2020 and NVDA 2020) is not alerted to confirm the filename selected. Also, the filename is not read back to them when re-focusing on the file input field.
Using Chrome's Shadow Dom, it can be seen that aria-hidden="true" is set […]

Great investigation work digging into the shadow DOM! However, this isn't caused by anything that GOV.UK Frontend is doing, and appears to be an issue with any file upload control in Chrome.

Looking at the source code for file input controls in Blink (the rendering engine for Chrome), it looks like the status text is 'hidden from AX trees for a historical reason' but I can't see any context as to what that reason might be!

Given it's a problem with the rendering engine, I don't think there's anything we can do to fix it in GOV.UK Frontend. I'd suggest 2 options:

1. You could raise an issue against 'Blink' explaining the problem. If you're comfortable doing this, I think this is the best approach – and you get to help improve the experience for Chrome users on every website, not just GOV.UK!
2. Alternatively, feel free to raise an issue against GOV.UK Frontend repo – but it's likely that all we'll be able to do is raise the issue against Blink ourselves.

[chris-gds]

Looking at the source code for file input controls in Blink (the rendering engine for Chrome), it looks like the status text is 'hidden from AX trees for a historical reason' but I can't see any context as to what that reason might be!

Really interesting...

Using Chrome's Shadow Dom, it can be seen that aria-hidden="true" is set on this content:

I started to wonder if you can target the Shadow DOM to override in some way or even lift / change the content out of the Shadow DOM 🤔

[shabana-ali]

@36degrees Thanks for your response.

400% zoom field width
Having style width: 100% for the file input does rescale the field but was there a reason for not doing this?

Apologies, I was supposed to reference the text input example as that is where width: 100% is used, e.g. https://design-system.service.gov.uk/components/text-input/default/index.html
I'll document this in the issue I raise on the govuk-frontend repo.

Filename not readout by screen readers

I'll raise an issue against 'Blink' explaining the problem.

[adamliptrot-oc]

I started to wonder if you can target the Shadow DOM to override in some way or even lift / change the content out of the Shadow DOM 🤔

You can interrogate the file list from the input with javascript.
I wrote this a few years back (so please ignore the questionable updating of the label) but it demonstrates the idea. https://codepen.io/adamliptrot/pen/VaOLaW

[shabana-ali]

Filename not readout by screen readers issue raised with Blink https://bugs.chromium.org/p/chromium/issues/detail?id=1147028

[meg-thomas]

On 'send documents for a customs check' we are using the add to list pattern combined with file upload to add multiple files. So far it has tested well with users in the sense that they have all been able to complete the tasks. Several users have commented that they would prefer to have drag and drop, and be able to upload several files at once.

One enhancement we made after research is that we added a message that appears when the user says they do not want to add any more files, to get across the message that they would be sending them. We considered having a further 'check your files' page, but felt that would be repetitive.

We have an 'uploading ring' shown next to the file upload button, which we believe is fully accessible.

[nhsbsa-dean]

Is there any information around the accessibility of the file being uploaded. For example, if a user is to upload a piece of evidence as a JPEG and then this evidence was to be checked, what if the user doing the check was visually impaired?

[terrysimpson99]

This component produces english text when the user selects welsh. For example 'Choose file' and 'No file chosen'. How can we resolve this? The answer is probably related to #99

[meg-thomas]

Following user feedback, our project has deviated from the standard pattern. Our users are generally frequent users, who use the service daily or several times a week. Speed is important to them, and we wanted to create a way for them to upload files more quickly. Ideally we wanted a multi-select file selection field, and also drag and drop. We have not been able to create an accessible way of doing this, however we now have several inputs on one page (up to 10 files can be added).

[36degrees]

This component produces english text when the user selects welsh. For example 'Choose file' and 'No file chosen'. How can we resolve this? The answer is probably related to #99

The text 'Choose file' / 'No file chosen' is part of the native input control provided by the browser, and will be localised to whatever language the user's operating system is set to. This means that unlike other parts of the web page, if the user's operating system language is also set to Welsh, then it will display in Welsh.

Unfortunately there is currently no way to localise or otherwise customise the text without hiding the native control and completely re-implementing it, which has its own challenges.

[terrysimpson99]

"[...] if the user's operating system language is also set to Welsh, then it will display in Welsh."

Interesting, I did not know that.

[Xoog]

Following user feedback, our project has deviated from the standard pattern. Our users are generally frequent users, who use the service daily or several times a week. Speed is important to them, and we wanted to create a way for them to upload files more quickly. Ideally we wanted a multi-select file selection field, and also drag and drop. We have not been able to create an accessible way of doing this, however we now have several inputs on one page (up to 10 files can be added).

I really like this, Meg. Do you have a repo with the code for this component?

[meg-thomas]

I really like this, Meg. Do you have a repo with the code for this component?

Here is the code Xoog : https://github.com/hmrc/trader-services-route-one-frontend

[CByrom]

I really like this, Meg. Do you have a repo with the code for this component?

Here is the code Xoog : https://github.com/hmrc/trader-services-route-one-frontend

Being another HMRC service, we've used Meg's design as a basis for our service's multi-file upload functionality, and it's tested well with users - we'd be happy to share research findings.

[RichardBray]

Here is how we've done it for the legalisation project.

You don't really see it in the video but there is a solid colour progress bar for the file upload and the stripe animation for the virus scan and other file checks.

This of course doesn't show if javascript is disabled.

progress_bar.mp4

[timpaul]

Evidence that younger generations have low awareness of file systems: https://www.theverge.com/22684730/students-file-folder-directory-structure-education-gen-z

[annahyphenkayINSS]

My understanding is that the upload page would have two buttons if javascript is turned off.

1. Upload (in grey)
2. Continue (green)

If this is true, then have any services seen feedback that users are confused about having multiple buttons on one page? and a continue button being displayed that they can't use until the upload has been done?

[CharlotteDowns]

We ran an external accessibility audit for some of the components and patterns in GOV.UK Frontend in May 2023. In that audit, we included an example of the File upload component. We’re adding results from that audit here so that we can:

• document, discuss and address the findings
• inform future contributors of the findings

Two accessibility issues raised

Issue 1: Usability

There's no visual target area when dragging and dropping a file. Make it clear how dragging works.

There is no indication provided for users to know that they can drag and drop files onto the page, as well as when doing so, any indication of where they can drop the file, possibly resulting in the file being dropped in an incorrect location and not being successfully added for uploading.

More detail in this issue:

• #3685

Issue 2: Usability

Dragon doesn't respond to 'click choose file' due to Dragon / browser bugs. Consider using button?

The ‘choose file’ input does not respond to any verbal command for users of voice activation software. This means that the user must use verbal keyboard commands such as ‘Press tab’ etc, in order to access the component.

More detail in this issue:

• #3686

[Jon-Rowe-HMRC]

HMRC have published supplemental file upload guidance for our department:
https://design.tax.service.gov.uk/hmrc-design-patterns/file-upload/

It includes:

• Suggested hint text
• How to allow multiple file uploads
• How to show file upload status in a way that’s both accessible and compatible with HMRC’s file upload backend
• How to remove files
• How to support labelling
• Further guidance on error messages

[GeorgeAlexandrouCDDO]

Hi
Currently iPhone HEIC files are not part of the permitted upload format list (e.g. JPG, JPEG, BMP, PNG, TIF or PDF).
Is the user need to successfully upload HEIC files part of the product backlog?
Thanks George Alexandrou (CDDO DM)

[owenatgov]

@GeorgeAlexandrouCDDO Thanks for the question.

This component is, in essence, an input with type="file" and some light styling. We have no control over what files are available to component as this is controlled entirely by the file upload API. I'm a bit surprised that this doesn't work. HEIC isn't mentioned in the list of MIME types in the HTML standard but I wouldn't expect that to prevent it from being uploaded.

Have you tried using the accept attribute to specify .heic? Using either the nunjucks macro:

{{ govukFileUpload({
  id: "file-upload-1",
  name: "fileUpload1",
  label: {
    text: "Upload a file"
  },
  attributes: {
    accept: ".heic"
  }
}) }}

...or html:

<div class="govuk-form-group">
  <label class="govuk-label" for="file-upload-1">
    Upload a file
  </label>
  <input class="govuk-file-upload" id="file-upload-1" name="fileUpload1" type="file" accept=".heic">
</div>

[Jonathon-Marc]

What

I am looking to build on the Multi File upload that currently does not exists in GDS but there are variations from HMRC and the MoJ which is most closely related to our use case for UKHSA.

Why

Explain why you think this should be added to the GOV.UK Design System.
We have a specific use case where users need to upload multiple files at once, over 100 files in one submission. After extensive research there is no component in use that allows users to do this.

• What evidence do you have that it's needed by multiple services across government?
• In my research I have seen multiple file upload being explored by HMRC, MoJ as well as other teams within UKHSA.
• What evidence do you have that it meets the needs of the users of those services?
• Have you checked that it doesn't already exist in the GOV.UK Design System?
• Yes

The proposal below deals with accessibility concerns from the MoJ iteration such as the use of green and red colours to distinguish if a file is ready to upload. It also has more details on upload space available and number of files uploaded.

Anything else

Include links to any examples, research or code to support your proposal, if available.

[matthewford]

Files need to be scanned for viruses after they have been uploaded; it would be great if the messaging to the user while the file is scanning and after the scan is also considered in this pattern. Usually, the file will be clean, but if it is not, or perhaps the file cannot be scanned, it would be good to provide feedback to the user.

On the Kings Awards for Enterprise service, we inform the user the file hasn't passed scanning and ask them to re-upload a new file.

[halimaikuomola]

Hello,
We are currently utilising the GDS file upload component in our service. However, we have received consistent user feedback highlighting several areas for improvement and pain points:

• The component feels clunky and difficult to use.
• There is a lack of clarity on how to upload multiple files, leading to user confusion.
• Many users have requested drag-and-drop functionality. While this feature is technically available within the GDS component, it is not clearly indicated in the design, and users are often unaware of its existence.
• Uploaded files do not appear in the same order as they were added, which may be an issue specific to our service, but it is impacting user experience.
  We are aware of the MOJ file upload component as an alternative; however, our tech team is hesitant to integrate the MOJ library at this time.

Are there any other recommended approaches or alternative components that could better address these issues?

[querkmachine]

@halimaikuomola It should be noted that the file input used in the Design System component isn't customised in any way, and is just a light wrapper around the browser's native input control.

We've been looking into improvements to the component very recently, some of which might come about in future, such as a more visual drag-and-drop experience.

Some other aspects you mention—like multiple file selection and the order in which files are listed—are relatively locked down and not easy to change without significantly changing how uploading works, which would need to be specific to the architecture of specific services and outside of the capabilities of the Design System offering.

[joelanman]

worth noting MOJ and HMRC have patterns for file uploads:

https://design-patterns.service.justice.gov.uk/components/multi-file-upload/

https://design.tax.service.gov.uk/hmrc-design-patterns/file-upload/

[OlagokeD]

To effectively accommodate WCAG 2.2 updates on file uploads and ensure users can reuse previously uploaded files, a "remove" link should be provided once a file is uploaded. This empowers user to decide when to delete a file, rather than having the system automatically remove it. This flexibility enhances usability and aligns with accessibility best practices.

For example, if a file upload is part of a filter alongside other inputs like checkboxes, users can retain the file for subsequent searches or remove it when it's no longer needed. Providing a "remove" link ensures users have full control over their uploaded files, improving both accessibility and the overall user experience.

User research has also shown that providing explicit controls, link a "remove" link, aligns with WCAG's emphasis on user autonomy and reduces frustration caused by automatic actions.