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

[suryanaga]

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

[suryanaga]

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

[Jonathon-Marc]

We are preparing for our Beta assessment. You can find our documentation and current and future screen design here

[Jonathon-Marc]

This is our final version that is fully accessible and truncated text in file names.

Best of luck to all!

[Jonathon-Marc]

File.upload.screen.recording.mov

[JustMehmet]

@Jonathon-Marc your component looks working for the requirements that you mentioned above.

I was unable to find any component as Choose files for uploading documents in gov-uk design system. Is it possible to share the github repository for it.

By the way, @querkmachine Is it okey to use @Jonathon-Marc' s upload files component?

Thanks.....

[mark-a-roberts]

I have been having problems using the latest version of the component in a Svelte/TypeScript environment

The DefinitivelyTyped @types/govuk-frontend only goes up to the previous version *4.8" at the present time

import { FileUpload, createAll } from 'govuk-frontend';

   	onMount(() => {
	createAll( FileUpload);
})

Fails to work.

[rachel-robson-hmrc]

File.upload.screen.recording.mov

Hi @Jonathon-Marc ,
Was just wondering if it's possible to get a fully functioning example of the uploading functionality into the design system at all?
Specifically the part that generates the list of uploaded items and shows them being validated as soon as they are dragged and dropped into the area?

Also, is the specific code that needs implemented on the frontend for this available anywhere?
Currently have a development team who are saying multiple uploads using drag and drop aren't catered for in the component, and we need to design in an interaction to actually upload them, but your video would suggest otherwise.

Any guidance would be massively appreciated.
Thank you.

[querkmachine]

Hi @rachel-robson-hmrc,

Regarding this part of your comment:

Was just wondering if it's possible to get a fully functioning example of the uploading functionality into the design system at all?
Specifically the part that generates the list of uploaded items and shows them being validated as soon as they are dragged and dropped into the area?

It's unlikely that we can include this functionality in the Design System. This is because it's dependent upon server-side code to asyncronously upload and validate each file. Client-side code, by itself, isn't able to do this.

Client-side code isn't able are they able to manage multiple files, as native file inputs can only hold a single value at a time (even if that 'single' value is actually multiple files) and browser security settings don't allow websites to manipulate that value. This again requires a server-side element to work properly, so isn't something that can be delivered wholly by the Design System.

[anandamaryon1]

Hi there, on the NHS design system we're working on porting over the File upload component.

We've noticed a few things we think are worth sharing back.

Dragon usage

In our testing we've found the following to be not quite accurate:

With the improved File upload component, users can say commands for interacting with web page controls to choose files.

However, due to browser security features, this may not work on subsequent interactions on the same page. If the component needs to be used more than once (for example, to correct a mistake), users will first need to perform another action, such as a mouse click.

We've found that Dragon users can interact with the (enhanced) file upload via voice commands, however, they first have to interact with the page, which seems to align with your link explaining user activation. They then need do so again for subsequent interactions with the file upload, as you mention.

We're thinking of using the following explanation:

Users of Dragon, a speech recognition tool, may not be able to interact with the component until they have first interacted with another part of the page. For example they could click the mouse in an empty area or they could say "press tab" to move the focus. After that, the Dragon user should be able to interact successfully with the file upload component.

If they need to use the component more than once (for example, to correct a mistake), they may need to perform another action again before using it.

Safari bug

I've found that in Safari (26.1), the chosen filename is not announced by VoiceOver, instead it says "no file chosen".

Disabled styling bug

When disabled if you click the label, you get some focus styling. (Chrome 142)

Tested in-browser by adding the disabled attribute and the govuk-drop-zone--disabled class. So maybe I'm missing something.

Design of states

We've simplified these slightly by removing the background hover change when a file is present (hover is still communicated via the button state).

[gonogo]

The pattern doesn't currently include guidance or HTML/Nunjucks code for handling multiple file uploads, removing uploaded files, and a progress indicator for files as they upload. I've been given some examples from the HMRC and MoJ design systems which are useful for this (thanks James Gordon and Oscar Duignan for the pointers):
HMRC design system
MoJ design system
MoJ design system (multi upload)

[CharlotteDowns]

In version 6.0 of GOV.UK Frontend we updated the colours of the file upload component to align with the updated GOV.UK colour palette. The new palette is updated on the GOV.UK Design System website (styles > colour)

[CharlotteDowns]

Hi folks, for the next few weeks we're reviewing the improved version of the File upload component in the GOV.UK Design System. Get in touch if you're using it, and if you want to suggest any improvements or findings from user research 🙏.

[jmflint27]

Does anyone have examples of adapting this component to include a file preview beyond a link?

I'm working on improvements to the "Upload your signature" journey on the Apply for a Postal or Proxy Vote sites. Because of the nature of the upload, it's important for users to be able to view the image and make sure it is suitable before they continue and have the image digitised for approval. We currently use a custom file upload component, but in user research have found that the arrow usage is slightly confusing. We are looking to update to something closer to the new GDS component, but are looking at how we might be able to preview the image.

[maykenworthy]

Hello,

I'm hoping this is the correct place to report bugs with the latest file upload component found here

I am working on the Cryptoasset Reporting Framework, where I am currently implementing the new version of the file upload component. During PR testing, a bug has been found with the component. The steps to recreate the bug are as follows:

1. Add a file to the component
2. Click continue to move to the next page
3. Use the back arrow in the top left of chrome to go back to the page with the component
4. The component will show itself as empty
5. As we have error checking in place, an error should show to let the user know they have not selected a file
6. When the user clicks continue in this state, the next page is loaded as if the file is present

Here is a video showcasing the steps listed above:
https://github.com/user-attachments/assets/03c18d3b-d9e9-471e-b2c0-4b05bb421ae1

Manual checks with logging has helped to identify that the file used to move on to the next page in steps 1 and 2 is still present in the component after the user goes back in step 3. This issue is not currently present in Firefox from what can be seen (the component does infact empty of the file when going back and the error checking works as expected).

Please feel free to contact myself on slack if you need any further info or if this is the wrong place for this.

Kind Regards, May Kenworthy

[Flora-Plan]

Multi-file uploader: design rationale

Why is it useful?

While it is possible to upload multiple files using the government design kit's upload component, there is no feedback around the progress of file uploads and no error messages highlighting which files cause errors.

Uploading multiple files is an essential part of our service at the planning inspectorate. The Ministry of Justice and HMRC have both created patterns for multi-file upload. Those patterns are less accessible than the pattern we've developed at the Planning Inspectorate. The table below explains where we have departed from the MOJ & HMRC components and why.

The multi file uploader in action

Multi.file.upload.component.in.action.mov

Moving the select files button before the drag and drop makes the order of actions clearer - while the redundant 'no file selected' error message is removed on initial page load. The file type hint text prevents errors seen in testing

File upload progress creates clarity for users uploading many files. Text upload progress rather than icons or progress bars offers more explicit meaning

A summary table showing uploaded files offers an opportunity for in-line error messaging.

Error messaging shows when files error but no action is needed for the user to remove the error file and continue

Design changes (vs MOJ and HMRC components)

Relevant component	Change	Why we changed/kept it	Evidence / notes
Choose files button	Move the Choose files button before the "or drop files" text	Faster and clearer for keyboard navigation (primary action presented first)	Focus order WCAG guide
Error messages	Add inline error messaging	Helps users recover from errors without losing progress	Observed need to recover quickly from upload errors in feedback on the live service. User quote: "Long upload time; error required repeating the process"; "Character limit only shown after attempt"
Error messages	Provide per-file errors in the list with remove + reupload	Allows fixing a single file without refreshing and losing progress	User quote: "Character limit only shown after attempt"
Summary list (progress indication)	Replace icons from the file summary list with text labels	Avoids different experiences for sighted vs non-sighted users	GOV.UK design system guidance on icons
Summary list (progress indication)	Add loading indication	Prevents repeated actions/errors when uploading large numbers of files (common behaviour)	Service behaviour: users often upload many files. User quote: "Takes some time to upload. Could be faster."
Summary list	Move the summary table below the upload area	Users did not notice the summary table when it was above the upload area	Usability testing: users failed to see the summary table above the upload area
Summary list	Maintaining summary list with added files and the option to remove or cancel uploads	Users liked to review the files they were about to upload and remove any duplicates before submitting the form	"Good to see on this screen that the files have been added before clicking continue. And to see what type it is e.g. pdf" "One participant mentioned that it was good to see the files that have been uploaded before continuing — it gives them reassurance that the files have been uploaded; otherwise they would keep trying to upload them." "Participant liked the option to be able to remove the file at the point of uploading — in case there is a human error to upload the [wrong file]."
Upload area	Make drag-and-drop a secondary action	Reflects findings from HMRC testing of multi-document upload	GOV file upload discussion
Upload area	Maintain drag and drop function	Continued to support drag and drop as users used this technique in testing	All participants successfully selected/dragged the files. Users split their screen in order to check and drag the files
Upload area	Remove "no file chosen" message	Avoids suggesting an error before the user interacts. The 'no file selected' message is redundant when using the files added summary list	HMRC includes the no file selected message, which we have removed
Upload area	Adding hover and focus states	Updating the component to be in line with the behaviour of the GOV.UK file-upload component	Makes the component more accessible and consistent with the GOV.UK design system
Upload area	Increase target size / larger click target by making the whole upload area clickable	Meets WCAG AAA minimum target size (44×44px). Faster to use; improves accessibility for users with sight and motor function issues	WCAG 3 target size guidance
File format hint text	Include file size and format in the component's hint text	To prevent errors for users when uploading files	Participant asked for file size limits labelling. "At statement stage you need to know the limit of what you can send out, so you know whether to go in two batches or one." Another user discovered: "Character limit only shown after attempt"

Feedback and research inputs

Feedback on the previous version of the multi-file uploader in the live service

Relevant component	Relevant aspect of the component	User quote / summary	Source
Error messages	Upload reliability / post-upload errors	"Half of the time you can't download, it tells you there is a fault when you upload documents… It's not fit for purpose."	Appeals back office feedback
Error messages	Validation messaging / limits clarity	Character limit only shown after attempt; appeal number not recognised	Interested parties feedback
Multi-file upload	Ability to upload multiple documents	Request to upload multiple documents at once (time-saving; aligns with other sections)	Appeals back office feedback
Multi-file upload	Ease of use / usability	"I found it difficult to upload documents."	Interested parties feedback
Multi-file upload	Uploading multiple files in public comments	No ability to upload separate files in public comments; may cause issues	Interested parties feedback
Summary list (progress indication)	Upload speed / progress feedback	"Slow on uploads and no progress bar like the old site."	Local Planning Authority feedback
Summary list (progress indication)	Upload speed and error recovery	Long upload time; error required repeating the process	Interested parties feedback
Summary list (progress indication)	Upload speed	"Takes some time to upload. Could be faster."	Interested parties feedback

Usability testing findings

• Users requested clarification over file upload limit wording.
• At least 4 users triggered errors due to special characters in filenames — brackets common for "(tracked)" and "(clean)"; dashes also common.
• Screen readers need to have announcements when uploading has started and is complete - announcements per file or per loading state can be overwhelming
• The 'remove' button needs to have the file name in visibly hidden text for screen readers to understand which files are being removed
• We needed a Javascript disabled version - in this instance the standard government file uploader can be used

[NickColley]

@Flora-Plan thanks for sharing! Do you have a link to your component guidance page and the source code? It might be useful in the future.