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.