Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

File input

Use with caution: Available USWDS v3
File input allows a single file to be uploaded.

Examples - v3

Default

View va-file-input in Storybook

Required

View va-file-input when required in Storybook

Accepts only specific file types

View va-file-input that accepts only specific file types in Storybook

Accepts any kind of image

View va-file-input that accepts any kind of image in Storybook

Error Message

View va-file-input error message in Storybook

Examples - v1

Default

View va-file-input in Storybook

Usage

Refer to the U.S. Web Design System for usage guidance

Additional guidance for VA

  • One file per input. This 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. Thus the VA implementation of this component does not deviate from our current pattern for handling multiple file uploads by prompting for each file with a new file input component. We will evaluate if we will change the behavior of this component at a later date.

How this component works

  • Pair with a label. Be sure to provide label text with the file input component.
  • 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

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.
uswds uswds boolean false Whether or not the component will use USWDS v3 styling.

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

Refer to the U.S. Web Design System for accessibility guidance

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.2 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.2 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.2 1.4.11).
Keyboard interactions
Follows WCAG 2.2 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
Edit this page in GitHub (Permissions required)
Last updated: Feb 27, 2024