Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

View cookies

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Upload

Overview

A file upload input allows a user to select a file from their computer's file system.

Open this example in a new tab (Example Upload)

Example Upload contents

Nunjucks

{% from "components/upload/_macro.njk" import onsUpload %}

{{
    onsUpload({
        "id": "file-example-upload",
        "accept": ".xls,.xlsx,.pdf",
        "label": {
            "description": "File types accepted are XLS and XLSX or PDF",
            "text": "Upload a file"
        }
    })
}}

Nunjucks macro options

NameTypeRequiredDescription
idstringtrueThe HTML id of the upload input. Sets the HTML for attribute on the label.
labelLabel (ref)trueSettings for the input label
acceptstringfalseSets the accepted file types: “file_extension”, “audio/”, “video/”, “image/”, “media_type”. Further information on this attribute at w3 schools (opens in a new tab) 
namestringfalseThe HTML name attribute for the upload input
attributesobjectfalseHTML attributes (for example, data attributes) to add to the upload input
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalseSet to “true” to prevent the upload input from being wrapped in a field component
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
errorError (ref)falseSettings for validation errors

HTML

<div class="ons-field">
  <div class="ons-field">
    <label class="ons-label ons-label--with-description" for="file-example-upload"
      aria-describedby="description-hint">Upload a file</label>
    <span id="description-hint" class="ons-label__description  ons-input--with-description">File types accepted are XLS
      and XLSX or PDF</span>
    <input type="file" id="file-example-upload"
      class="ons-input ons-input--text ons-input-type__input ons-input--upload" accept=".xls,.xlsx,.pdf"
      aria-describedby="description-hint" />
  </div>
</div>

When to use this component

Use this component when there is a requirement for a user to select and submit a local file as part of their task.

How to use this component

The <input> value is set to type="file". A file upload input also takes the attribute accepts= which take a comma separated list of file extensions with the . prefix for example: accept=".xls,.xlsx,.pdf".

How to check uploads

To help users upload a file, you should:

  • check they have uploaded something
  • check that what they have uploaded is a valid file type
  • show an error message if they have not uploaded anything or what they have uploaded is not a valid file type

Error messages

Use the correct errors pattern and show the error details above the checkbox options.

Open this example in a new tab (Example Upload Error)

Example Upload Error contents

Nunjucks
{% from "components/upload/_macro.njk" import onsUpload %}

{{
    onsUpload({
        "id": "file-example-upload-error",
        "accept": ".xls,.xlsx,.pdf",
        "label": {
            "description": "File types accepted are XLS and XLSX or PDF",
            "text": "Upload a file"
        },
        "error": {
            "id": "file-error",
            "text": "Select a file that is an XLS, XLSX or PDF"
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the upload input. Sets the HTML for attribute on the label.
labelLabel (ref)trueSettings for the input label
acceptstringfalseSets the accepted file types: “file_extension”, “audio/”, “video/”, “image/”, “media_type”. Further information on this attribute at w3 schools (opens in a new tab) 
namestringfalseThe HTML name attribute for the upload input
attributesobjectfalseHTML attributes (for example, data attributes) to add to the upload input
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalseSet to “true” to prevent the upload input from being wrapped in a field component
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
errorError (ref)falseSettings for validation errors
HTML
<div class="ons-panel ons-panel--error ons-panel--no-title" id="file-error">
  <span class="ons-panel__assistive-text ons-u-vh">Error: </span>
  <div class="ons-panel__body">
    <p class="ons-panel__error">
      <strong>Select a file that is an XLS, XLSX or PDF</strong>
    </p>
    <div class="ons-field">
      <div class="ons-field">
        <label class="ons-label ons-label--with-description" for="file-example-upload-error"
          aria-describedby="description-hint">Upload a file</label>
        <span id="description-hint" class="ons-label__description  ons-input--with-description">File types accepted are
          XLS and XLSX or PDF</span>
        <input type="file" id="file-example-upload-error"
          class="ons-input ons-input--text ons-input-type__input ons-input--upload ons-input--error"
          accept=".xls,.xlsx,.pdf" aria-describedby="description-hint" />
      </div>
    </div>
  </div>
</div>

If no file has been selected

Use “Select a [whatever they need to select]”.
For example, “Select a report”.

If there was a problem and the file was not uploaded

Use “The selected file could not be uploaded. Please try again”.

If the file is the wrong file type

Use “Select a file that is [list of file types]”.
For example, “Select a file that is an XLS, XLSX or PDF”.

If the file is too big

Use “Select a file that is smaller than [largest file size]”.
For example, “Select a file that is smaller than 2MB”.

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Upload’ component on GitHub (opens in a new tab)