Upload
A file upload input allows a user to select a file from their computer’s file system.
<div class="ons-field">
<div class="ons-field">
<label class="ons-label ons-label--with-description" for="file">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" class="ons-input ons-input--text ons-input-type__input ons-input--upload" accept=".xls,.xlsx,.pdf" aria-describedby="description-hint" />
</div>
</div>{% from "components/upload/_macro.njk" import onsUpload %}
{{
onsUpload({
"id": "file",
"accept": ".xls,.xlsx,.pdf",
"label": {
"description": "File types accepted are XLS and XLSX or PDF",
"text": "Upload a file"
}
})
}}
{% macro onsUpload(params) %}
{% from "components/input/_macro.njk" import onsInput %}
{% from "components/field/_macro.njk" import onsField %}
{% set field %}
{{ onsInput({
"id": params.id,
"type": "file",
"label": params.label,
"classes": "ons-input--upload" + (" ons-input--error" if params.error else ""),
"accept": params.accept,
"name": params.name,
"attributes": params.attributes,
"listeners": params.listeners
}) }}
{% endset %}
{% call onsField({
"id": params.fieldId,
"classes": params.fieldClasses,
"dontWrap": params.dontWrap,
"error": params.error
}) %}
{{ field | safe }}
{% endcall %}
{% endmacro %}
.ons-input--upload {
background: $color-white;
border: 1px solid $color-input;
border-radius: $input-radius;
font-size: 1rem;
padding: 0;
width: 100%;
&::-webkit-file-upload-button {
background: $color-button-secondary;
border: 0;
border-bottom-right-radius: 0;
border-right: 1px solid $color-input;
border-top-right-radius: 0;
color: $color-text;
font-size: 1rem;
outline: none;
padding: 0.5rem 1rem;
transition: border-color 200ms ease-in;
}
&:hover {
cursor: pointer;
&::-webkit-file-upload-button {
border-right-color: $color-text-link-hover;
cursor: pointer;
}
}
@include mq(m) {
width: 80%;
}
@include mq(l) {
width: 70%;
}
}
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.
<div class="ons-panel ons-panel--error ons-panel--no-title" id="file-error">
<span class="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">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" 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>{% from "components/upload/_macro.njk" import onsUpload %}
{{
onsUpload({
"id": "file",
"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",
"dsExample": isPatternLib
}
})
}}
{% macro onsUpload(params) %}
{% from "components/input/_macro.njk" import onsInput %}
{% from "components/field/_macro.njk" import onsField %}
{% set field %}
{{ onsInput({
"id": params.id,
"type": "file",
"label": params.label,
"classes": "ons-input--upload" + (" ons-input--error" if params.error else ""),
"accept": params.accept,
"name": params.name,
"attributes": params.attributes,
"listeners": params.listeners
}) }}
{% endset %}
{% call onsField({
"id": params.fieldId,
"classes": params.fieldClasses,
"dontWrap": params.dontWrap,
"error": params.error
}) %}
{{ field | safe }}
{% endcall %}
{% endmacro %}
.ons-input--upload {
background: $color-white;
border: 1px solid $color-input;
border-radius: $input-radius;
font-size: 1rem;
padding: 0;
width: 100%;
&::-webkit-file-upload-button {
background: $color-button-secondary;
border: 0;
border-bottom-right-radius: 0;
border-right: 1px solid $color-input;
border-top-right-radius: 0;
color: $color-text;
font-size: 1rem;
outline: none;
padding: 0.5rem 1rem;
transition: border-color 200ms ease-in;
}
&:hover {
cursor: pointer;
&::-webkit-file-upload-button {
border-right-color: $color-text-link-hover;
cursor: pointer;
}
}
@include mq(m) {
width: 80%;
}
@include mq(l) {
width: 70%;
}
}
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 component
Let us know how we could improve this component or share your user research findings. Discuss the ‘Upload’ component on GitHub