Components
File input
File input allows users to attach one or multiple files.
<div class="usa-form-group">
<label class="usa-label" for="file-input-single"
>Input accepts a single file</label
>
<input
id="file-input-single"
class="usa-file-input"
type="file"
name="file-input-single"
/>
</div>
<div class="usa-form-group">
<label class="usa-label" for="file-input-specific"
>Input accepts only specific file types</label
>
<span class="usa-hint" id="file-input-specific-hint"
>Select PDF or TXT files</span
>
<input
id="file-input-specific"
class="usa-file-input"
type="file"
name="file-input-specific"
aria-describedby="file-input-specific-hint"
accept=".pdf,.txt"
multiple="multiple"
/>
</div>
<div class="usa-form-group">
<label class="usa-label" for="file-input-wildcard"
>Input accepts any kind of image</label
>
<span class="usa-hint" id="file-input-wildcard-hint"
>Select any type of image format</span
>
<input
id="file-input-wildcard"
class="usa-file-input"
type="file"
name="file-input-wildcard"
aria-describedby="file-input-wildcard-hint"
accept="image/*"
multiple="multiple"
/>
</div>
<div class="usa-form-group">
<label class="usa-label" for="file-input-multiple"
>Input accepts multiple files</label
>
<span class="usa-hint" id="file-input-multiple-hint"
>Select one or more files</span
>
<input
id="file-input-multiple"
class="usa-file-input"
type="file"
name="file-input-multiple"
aria-describedby="file-input-multiple-hint"
multiple="multiple"
/>
</div>
<div class="usa-form-group usa-form-group--error">
<label class="usa-label usa-label--error" for="file-input-error"
>Input has an error</label
>
<span class="usa-hint" id="file-input-error-hint">Select any valid file</span>
<span class="usa-error-message" id="file-input-error-alert"
>Display a helpful error message </span
><input
id="file-input-error"
class="usa-file-input"
type="file"
name="file-input-error"
aria-describedby="file-input-error-hint"
/>
</div>
<div class="usa-form-group">
<label class="usa-label" for="file-input-disabled"
>Input in a disabled state</label
>
<input
id="file-input-disabled"
class="usa-file-input"
type="file"
name="file-input-disabled"
disabled="disabled"
/>
</div>
Guidance
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.
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>
’sid
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 standardfile
input.
Using the file input component
- 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 [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
data-errorMessage
tousa-file-input
to include a custom error message.
File input settings
This component has no settings.
File input variants
This component has no variants.
Package
-
Package usage:
@forward "usa-file-input";
- Dependencies:
uswds-fonts
Latest updates
Meaningful code and guidance updates are listed in the following table:
Date | USWDS version | Affects | Description |
---|---|---|---|
2022-04-28 | N/A |
|
Updated package name to |
2022-04-28 | 3.0.0 |
|
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656 |
2022-04-13 | N/A |
|
Updated package name to |
2021-12-14 | 2.13.0 |
|
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 |
2021-11-01 | 2.12.2 |
|
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 |
2021-11-01 | 2.12.2 |
|
Added automatic sanitizing. The design system now automatically sanitizes content in elements we compose with JavaScript. This means that components like combo box, tooltip, file input, and date picker will sanitize any content passed to them. This helps protect any design system implementation against malicious XSS attacks through these components. More information: uswds#4329 |
2021-09-20 | N/A |
|
Added documentation for using |
2021-06-07 | N/A |
|
Updated package name to |