Components

File input

File input allows users to attach one or multiple files.

Select PDF or TXT files
Select any type of image format
Select one or more files
Select any valid file Display a helpful error message 
<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>

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>’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.

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 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.

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
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