File input

File input allows users to attach one or multiple files.

Must be a PDF Any file type
Helpful error message
1
2
3
4
5
6
7
8
9
10
11
12
13
<label class="usa-label" for="input-single">Single file</label>
<span class="usa-hint" id="input-single-hint">Must be a PDF</span>
<input id="input-single" class="usa-file-input" type="file" name="input-single" accept=".pdf" aria-describedby="input-single-hint" />

<label class="usa-label" for="input-multiple">Multiple files</label>
<span class="usa-hint" id="input-multiple-hit">Any file type</span>
<input id="input-multiple" class="usa-file-input"  type="file" name="input-multiple" aria-describedby="input-multiple-hit" multiple />

<div class="usa-form-group usa-form-group--error">
  <label class="usa-label usa-label--error" for="file-input-error">Error example</label>
  <span class="usa-error-message" id="file-input-error-message" role="alert">Helpful error message</span>
  <input id="file-input-error" class="usa-file-input" multiple type="file" name="file-input-error" aria-describedby="file-input-error-message"/>
</div>

When to use the file input

  • Documents are required. Ask users to provide files when it's necessary.

When to consider something else

  • Documents are optional. Avoid asking users to provide documents if you don't require them.
  • Asynchronous upload. The file input component doesn't support asynchronous uploading. Files are POSTed only on form submission.
  • Asking for large files. Be mindful that some users might have limited connectivity or data plans.

Usability guidance

  • Allow multiple file formats. Not everyone has access to the same software. Be flexible with file types to avoid unnecessary software requirements.
  • Prefer one file per input. Some users might not know how to select multiple files in a file browser. Additionally, iOS does not allow multiple-file selection using the Files app.
  • Highlight input restrictions. Use usa-hint to be clear about any file restrictions, such as document types or file size.

Accessibility

  • Use proper labels and attributes. Each file input should have a <label>. Associate the two by matching the <label>’s for attribute to the <input>’s id attribute.
  • Use as a progressive enhancement. The file input component should be a progressive enhancement of <input type="file" />. If the component doesn't initialize, it should still work and appear like a standard file input.

Implementation

  • Initialization properties. JavaScript will create most elements for file input. To get a file input to initialize, add the class name usa-file-input to <input type="file" />.
  • Interaction. When a user selects or drags documents to the file input, the file name and a thumbnail preview are listed.
  • Using the accept attribute. You can allow certain files by placing an accept attribute on the <input/>If a file type is not accepted, the file will not be attached and the file input will display a message. Learn more about the accept attribute.
  • Internet Explorer/Edge These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.
File input settings

This component has no settings.

File input variants

This component has no variants.

Package information

  • Package usage: @import form-controls
  • Requires: required, global