Components
File input
Use with caution: Candidate
File input allows a single file to be uploaded.
Examples
Default
View va-file-input in Storybook
Required
View va-file-input in Storybook
Error Message
View va-file-input in Storybook
Usage
When to use va-file-input
- Uploading files. The file input component allows a user to provide required files, one at a time.
When to consider something else
- Documentation is 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.
How this component works
- Pair with a label. Be sure to provide label text with the file input component.
- Prefer one file per input. The file input component only supports one file upload at a time. 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 hint-text to be clear about any file restrictions, such as file types or maximum size.
Behavior
- Trigger: The file input button triggers a micro-interaction that causes the Operating System (OS) to present a dialog that prompts the user to select a file to upload.
- Rules: Once the file is uploaded, the browser presents a dialog to inform the user of the success or failure of the upload. The uploaded file can then be removed by the user, if necessary. Additional files can be uploaded, one by one.
- Feedback: The Progress bar - Activity component should be used to provide feedback to the user while the file is uploading.
Errors
- The error message is placed above the file input button.
- To display a custom error message, pass text into the
error
property. - See form error handling for additional guidance.
Code usage
Attributes and Properties
Property | Attribute | Type | Default | Description |
---|---|---|---|---|
accept |
accept |
string |
A comma-separated list of unique file type specifiers. | |
buttonText |
button-text |
string |
The text displayed on the button. | |
enableAnalytics |
enable-analytics |
boolean |
false |
Emit component-library-analytics events on the file input change event. |
error |
error |
string |
The error message to render. | |
hint |
hint |
string |
Optional hint text. | |
label |
label |
string |
The label for the file input. | |
name |
name |
string |
The name for the input element. | |
required |
required |
boolean |
false |
Sets the input to required and renders the (*Required) text. |
Events
Name | Description |
---|---|
component-library-analytics |
The event used to track usage of the component. This is emitted when the file input changes and enableAnalytics is true. |
vaChange |
The event emitted when the file input value changes. |
Content considerations
- Use explicit and specific words for actions. We prefer “upload” and “delete” as those words describe exactly what will happen when you tap or click.
- Upload instead of add. Use the word “Upload” instead of “Add”. For example, “Upload file” and “Upload another file”.
- Delete instead of remove. Use the word “Delete” instead of “Remove”. For example, “Delete file”. Also, do not use “Edit” unless the uploaded file can actually be edited in place. “Edit” is not appropriate for an uploaded file if the user has to delete and re-upload the file.
- Use file instead of document. File is the broadest term and thus preferable to “document” as that may be too specific when images, text files, and other file types may be acceptable for upload.
- Follow messaging guidance. Follow the feedback messages in the messages dictionary for file upload success and failure.
Accessibility considerations
- Use proper labels and attributes. When a label is supplied to the
label
property of the component, it will be associated with the<input>
element that has a matching id attribute automatically.
Component checklist
Maturity
- Guidance
- Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
- Research
- VFS team conducted research on this component which is linked from this page.
- Stability
- Component has been in production for more than 3 months with no significant issues found.
- Note: This component was converted from React to a web-component in August 2022.
- Adoption
- Multiple teams have adopted this component.
Accessibility
- Accessible use of color
- Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).
- Accessible contrast
- Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3). Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).
- Keyboard interactions
- Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions. All interactive elements can be selected and activated using the keyboard.
- Content zoom tested
- Component has been tested with the display set to 400% at 1280px viewport width to ensure that the component does not have overlapping text or elements and all interactive elements still operate.
- Tested in screen readers
- Tested with screen readers to ensure there are no issues with reading order, spelling, dynamic content, and interactive elements.
Code assets
- Variations
- Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
- Responsive
- Component depicted in all responsive breakpoints.
- Interactive states
- Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
- Tokens
- All design attributes (color, typography, layout, etc.) are available as tokens.
- Internationalization
- Describes i18n attributes.
Visual assets
- Variations
- Sketch library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
- Responsive
- Component designed to work in all responsive breakpoints.
- Interactive states
- Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
- Tokens
- All design attributes (color, typography, layout, etc.) are available as tokens.
93% complete (14 of 15)
Legend:
- Complete
- Incomplete
- Not applicable