File input

File input allows users to attach one or multiple files.

Select PDF or TXT files <input id="file-input-specific" class="usa-file-input" type="file" name="file-input-specific" aria-describedby="file-input-specific-hint"accept=".pdf,.txt"/>
Select one or more files <input id="file-input-multiple" class="usa-file-input" type="file" name="file-input-multiple" aria-describedby="file-input-multiple-hint"multiple/>
Select any valid file Display a helpful error message
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
<!-- Start: @file-input--default -->
<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>
<!-- End: @file-input--default -->

<!-- Start: @file-input--specific -->
<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"/>
</div>
<!-- End: @file-input--specific -->

<!-- Start: @file-input--multiple -->
<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/>
</div>
<!-- End: @file-input--multiple -->

<!-- Start: @file-input--error -->
<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" role="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>
<!-- End: @file-input--error -->

<!-- Start: @file-input--disabled -->
<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/>
</div>
<!-- End: @file-input--disabled -->

When to use the file input

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

Implementation

  • 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.
  • Internet Explorer/Edge These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.
File input settings

This component has no settings.

File input variants

This component has no variants.

Package information

  • Package usage: @import form-controls
  • Requires: required, global