Components

File input

File input allows users to attach one or multiple files.

Passed WCAG 2.1 AA

Testing has revealed some issues with this component. Learn more in the known issues section on this page.

Input accepts a single file

Input accepts only specific file types

Select PDF or TXT files

Input accepts any kind of image

Select any type of image format

Input accepts multiple files

Select one or more files

Input has an error

Select any valid file Display a helpful error message 

<h3 class="site-preview-heading">Input accepts a single file</h3>
<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>

<h3 class="site-preview-heading">Input accepts only specific file types</h3>
<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>

<h3 class="site-preview-heading">Input accepts any kind of image</h3>
<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>

<h3 class="site-preview-heading">Input accepts multiple files</h3>
<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>

<h3 class="site-preview-heading">Input has an error</h3>
<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>

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 will POST 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.
  • Use hint text to highlight input restrictions. Create an element with the usa-hint class to explain any file restrictions, such as document types or file size.

Accessibility guidance

Test the file input component in your own project.

USWDS tested the file input component for accessibility. You should test your implementation, too.

Use file input accessibility tests
  • Use proper labels and attributes. Each file input should have a label element. Associate the label to your input by defining the value of the label’s for attribute with the input’s id.
  • 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.

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.
  • Limit accepted file types with the accept attribute. Add the accept attribute to the input element when you want to limit the types of files your input can accept. If a user selects a file that does not match the specified type, the file will not be attached and the file input will display an error message. Learn more about the accept attribute [mozilla.org].
  • Internet Explorer and older versions of 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 to usa-file-input to include a custom error message.

File input settings

This component has no settings.

File input variants

This component has no variants.

Accessibility test status

The USWDS team did 15 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
15 13 2 0 0

Overview of recent accessibility test results:

  • Passed: 13
  • Passed with exceptions: 2
  • Conditional: 0
  • Failed: 0

Learn more on the file input accessibility tests page.

Known issues

All known issues for file input are tracked in GitHub . Notable usability issues are tracked below:

  • Screen reader users found it confusing to have both “Drag file here” and “Choose from folder” actions described in a single button. More information on GitHub: uswds#5616

Help fix these issues or add details on GitHub. Don't have an account? Please join our community to share feedback and contribute to USWDS.

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 Breaking Description
2024-11-19 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2963

2024-11-13 3.10.0
  • JavaScript
 No

Fixed a bug that caused image previews to break when a Content Security Policy is enabled. The component now uses event listeners in place of inline JavaScript to handle error states. More information: uswds#5997

2024-03-13 N/A
  • Guidance
 No

Added known issues section. More information: uswds-site#2402

2023-06-09 3.5.0
  • Guidance
 No

Removed disabled file input variant preview. More information: uswds-site#2114

2023-06-09 3.5.0
  • Accessibility
  • JavaScript
  • Styles
 No

Improved the file input experience for voice command and screen reader users. Voice command users can now interact with the component by speaking the visible instructions text. Additionally, screen reader users now have access to both the instructions text and the file selection status. More information: uswds#5213

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency and visibility of disabled styles. Form elements with the disabled or aria-disabled attribute now get consistent styling and have proper color contrast. More information: uswds#5063

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency of disabled styles in forced colors mode. More information: uswds#5295

2023-06-09 3.5.0
  • JavaScript
 No

Fixed a bug that caused large files to trigger an infinite spinner. Adding large files should now result in an accurate preview. More information: uswds#5114

2022-04-28 N/A
  • Guidance
 No

Updated package name to usa-file-input. More information: uswds-site#1538

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2022-04-13 N/A
  • Guidance
 No

Updated package name to form-controls. More information: uswds-site#1497

2021-12-14 2.13.0
  • Accessibility
  • JavaScript
 No

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
  • JavaScript
 No

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
  • JavaScript
 No

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
  • Guidance
 No

Added documentation for using data-errorMessage. More information: uswds-site#1269

2021-06-07 N/A
  • Guidance
 No

Updated package name to usa-form-controls. More information: uswds-site#1219