File input allows users to attach one or multiple files.
When to use the file input component
- 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.
- 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-hintto be clear about any file restrictions, such as document types or file size.
- Use proper labels and attributes. Each file input should have a
<label>. Associate the two by matching the
<label>’s for attribute to the
- 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
Using the file input component
<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
acceptattribute. 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 [mozilla.org].
- Internet Explorer/Edge. These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.
- Customizing the error message. Add the data attribute
usa-file-inputto include a custom error message.
File input settings
This component has no settings.
File input variants
This component has no variants.
Meaningful code and guidance updates are listed in the following table:
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656
Updated file upload to confirm files to screen readers. Now file input will tell screen readers the total number of files and the names of files added to the component. More information: uswds#4415
Fixed a duplicate file bug in file input. If a file with the same name was uploaded in two separate file input fields, the preview spinner would spin indefinitely. We now assign each upload an individual ID, and the image preview loads properly. More information: uswds#4313