Component status
| PublishedElement can be used in production | |
| PublishedElement can be used in production | |
Angular | In backlogElement is in backlog |
React | In backlogElement is in backlog |
Documentation | PublishedElement can be used in production |
File Input
File input is an interactive field that allows users to select files. It’s commonly used in form patterns.
Contents
What's newCopy link to this section
Copy link to this section
File input is a new, standalone component. In v1, file input was grouped with the inputs component. This component has been redesigned to the updated font ramp and color palette, in addition to accessibility enhancements.
AnatomyCopy link to this section
Copy link to this section
File input contains four elements:
- Label: describes the purpose of the file.
- Helper text: describes the file format and size guidelines.
- Button: launches the file selector.
- File: shows the name, size, and status with the option to dismiss.
Contents
Contents
UsageCopy link to this section
Copy link to this section
File input uses a browse button to launch a file selector dialog. Refer to the button component page for more information on how to use buttons. While not a part of the file input component, a submit button is usually the final step for uploading a file.
Users can select multiple files at once, as long as page upload requirements are respected. Each selected file will be treated as unique in the file list. If a file is chosen more than once, it will appear as a duplicate in the list.
Form submission
Most of the time, file input will be used in conjunction with a form. This might be for the purpose of attaching supporting documentation in an e-commerce checkout flow, such as a PDF of a purchase agreement. Or, it could be used in a productivity application, such as a spreadsheet of business expenses.
In a form, file input uses a secondary button so as to not compete with the primary form submit button.
Standalone submission
File input may occasionally have a use case as a standalone component. If it automatically uploads upon file selection (without a submit button) or brings users to another workflow (such as modal used to crop or edit a profile picture), then it is critical to communicate these expectations up front for accessibility.
When using file input as a standalone component without a submit or upload button, the browse button may be a primary button.
Errors
Errors appear when the input entry, or lack thereof, fails validation. In that case, use an error message and alert icon to describe the error and how to fix it as clearly and succinctly as possible. There are two types of error messages: component and file. Component-level error messages refer to an error affecting the submission success of the entire file input component, such as when the input is incomplete. File-level error messages refer to specific files, such as one that’s too big to upload.
Error state with component error message and file error message.
KindsCopy link to this section
Copy link to this section
Helper text allows users to accurately understand the file input parameters before selecting a file. Parameters are likely to include guidance on individual file size, number of files that can be selected at the same time, number of files that can be selected total, and valid file types. Valid file types should be listed by their file extension, not program; for example, list “.XLSX” instead of “Excel”, as multiple file formats are supported in Excel.
Default helper text: body text, to be used in most cases
Tooltip helper text: use in smaller sizes to save on vertical space
SizesCopy link to this section
Copy link to this section
The file input component is available in two sizes, large and small. On smaller screens, the file title is truncated in the middle so that the extension is always visible. A tooltip will be applied to show the entire file name on hover. Error messages will wrap to a second line on smaller screens, similar to the notification component.
Large file input component.
Small file input component.
InteractionCopy link to this section
Copy link to this section
Behaviors and states
A selected file can display a ready to submit state or an error state. Both states in the file list are dismissible. Error states will consist of an inline error message beneath the component and a file-level error message in the list.
If teams choose to enhance the behaviors of the component, designs for the base file states can be found in the Figma design panel. While not linked programmatically to the component, these states can be toggled to find designs for loading and success feedback, in addition to error and ready to submit states.
Button states, such as rest, hover, focus, inactive, and error, can be found in detail on the button component page.
Dismissible ready to submit and error states with elective loading and success states.
| State | Behavior |
|---|---|
| Ready to submit | A ready state will appear automatically with a white background after a file has been successfully selected and is able to be uploaded upon submission. |
| Error | A file input will appear in an error state of Red 100 with an alert icon when selection was interrupted, an invalid file format or size was selected, or a technical issue occurred. |
Standards Copy link to this section
Copy link to this section
Accessibility
Make sure all helper text and error messages provide meaningful assistance in helping users avoid or fix errors
Don’t provide unclear helper text, such as “Select a valid file format.” Instead, make it clear what a valid file format is.
WCAG 2.1: 3.3.2 Labels or Instructions, 3.3.3 Error Suggestion
Inform the user of an automatic upload behavior
Ensure a predictable experience for the user by informing them at the outset of uncommon patterns. For example, a user with a cognitive difficulty may expect to review the file again before submitting to upload and may become confused when it uploads automatically after selection.
WCAG 2.1: Understanding Success Criterion 3.2.2: On Input
Make sure all labels are clear, concise, and unique
All users should know from the label exactly what information is needed to successfully complete the field or operation.
WCAG 2.1: 1.3.1 Info and Relationships
Content
List file limitations
Clearly spell out accepted file types, file size, and quantity in the instructions. If users are shown an error, be specific on what caused the error and how to fix it.
Do: This file exceeds the 5 MB size limit. Select a smaller file to continue.
Don’t: Invalid file
Communicate expected outcome
In general, files are not uploaded until after a form is submitted. Communicate file upload status accurately.
Contents
Contents
Live demoCopy link to this section
Copy link to this section
This demo lets you interact with the component and view the code. To see other interactive examples of this component or for additional developer documentation, visit Storybook.
You are now entering a live demo of the component.
<div class="dds__file-input" data-dds="file-input">
<label id="file-input-label-861422857" class="dds__file-input__label" for="file-input-control-name-861422857">Label</label>
<small id="file-input-helper-861422857" class="dds__file-input__helper-text">Helper text</small>
<input
aria-hidden="true"
id="file-input-control-861422857"
type="file"
name="file-input-control-name-861422857"
class="dds__file-input__control"
accept=""
multiple=""
/>
<button
class="dds__button dds__button--secondary dds__button--md dds__file-input__button"
aria-describedby="file-input-label-861422857 file-input-helper-861422857"
>
<svg class="dds__icon dds__button__icon--start" focusable="false">
<use xlink:href="#dds__icon--upload"></use>
</svg>
Browse Files
</button>
<div id="file-input-error-861422857" aria-live="polite" class="dds__error-text">
<i class="dds__icon dds__icon--alert-notice dds__error-text__icon" aria-hidden="true"></i>
Error Text
</div>
</div>