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>

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