File upload

<div class="ds_question">
    <div class="ds_file-upload" data-module="ds-file-upload">
        <label class="ds_label" for="file-upload">Upload a file</label>
        <input class="ds_file-upload__input" id="file-upload" name="file-upload" type="file" />
    </div>
</div>

About this component

Use the file upload component to let users choose a single file for upload.

To select a file, the user can either:

• drag and drop a file into the file drop zone
• use the ‘Choose file’ button

Displaying the chosen file

After the user selects a file:

• the file name displays above the button, replacing the ‘no file chosen’ text
• the dashed border of the drop zone becomes a solid line

This tells the user they’ve selected a file for upload.

When to use file upload

Use the file upload component when the user needs to upload a file as part of their journey – for example, if they need to upload a receipt or proof of identity in a form.

Only ask users to upload files if essential

Only ask users to upload a file if it's necessary.

Some users may find uploading difficult because they may need to:

• scan a document or take a photo
• move a file from one device to another
• upload using limited bandwidth or data

How to use file upload

Label and button text

Include a label above the component that tells users what they can upload. This can be general or specific. For example:

• ‘Upload a file’ if any type of file is allowed
• ‘Upload a document’ if only documents are allowed

Use short, clear button text. For example, ‘Choose file’.

Help users choose the right file

Add text above the component explaining any file requirements, such as:

• file type – for example, ‘the file must be a JPG, BMP, PNG, TIF or PDF’
• maximum file size – for example ‘the file must be no larger than 10 MB’

Specify which file types can be uploaded

Use the HTML accept attribute to specify which file types a user can upload. For example, you could allow certain file extensions, MIME types or media types.

When you restrict file types using the accept attribute:

• files that do not match your allowed types will be greyed out in the file picker
• the component’s JavaScript will block drag‑and‑drop uploads of any files that are not allowed

Replacing a chosen file

Allow users to replace the file they've chosen.

They can do this by choosing a different file using the button or dropping a new file into the drop zone.

Show an optional progress bar

You can add a progress bar to show the user the upload progress. This can be helpful for large file uploads.

Place the progress bar below the file upload component.

Show confirmation of success 

Tell users when their file has been uploaded successfully. 

Use a confirmation message or notification panel after the upload has completed. Choose the right one for your use case. 

Error messages

Show an error message if there’s a problem with the file upload. 

Style the error message as shown in the error message guidance. 

<div class="ds_question  ds_question--error">
    <div class="ds_file-upload" data-module="ds-file-upload">
        <label class="ds_label" for="file-upload">Upload a file</label>
        <p class="ds_question__error-message">The selected file must be smaller than 2MB</p>
        <input aria-invalid="true" class="ds_file-upload__input  ds_file-upload__input--error" id="file-upload" name="file-upload" type="file" />
    </div>
</div>

Use specific error messages

Use a specific error message for each error state.

If no file has been selected

Say ‘Select a file to continue’.

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

Allow users to reuse uploaded files

Let users reuse a file they’ve already uploaded within the same journey, unless doing so would be a major security or privacy concern. For example, a user may need to upload a photo of their passport to prove their identity, and again to prove their address.

This ensures your service meets the Web Content Accessibility Guidelines (WCAG) criterion 3.37 (redundant entry).

Make it easy for a user to reuse a previously uploaded file. Show it as an option for them to select so they do not need to upload it again.

Consider users on public devices before choosing to make the file available to preview or download.

Accessibility

The file upload component makes a standard HTML file input easier to use and more accessible because:

• the drop zone is larger and clearly marked, so people can see where to add a file
• screen readers tell users when a file is dragged into or out of the drop zone

Evidence

User research

We tested the file upload component as part of user testing carried out on a planning application form.

Users were able to use the drag and drop function without issues. They recognised that they could drag and drop files into the area. The full‑width drop zone successfully captured all the files they dragged into it.

Website analytics

You can track file upload components through:

• the original page path
• a data attribute identifying the file upload’s input element

The Design System's 'tracking' script adds this attribute.

Tracking attributes

The input element in a file upload component gets a data-form attribute. Its value uses the pattern fileinput-[field ID].

<input class="ds_file-upload__input" id="my-file" type="file" data-form="fileinput-my-file">

When a file is selected, the input element gets 2 additional attributes:

• data-filesize, giving the selected file's size in kB
• data-filetype, giving the selected file's file extension in lower case text

Those 2 attributes are removed if the file is deselected.

<input class="ds_file-upload__input" id="my-file" type="file" data-form="fileinput-my-file" data-filesize="1234kB" data-filetype="pdf">

Error message tracking

You can track the website analytics for file upload error messages using the error message tracking.