Components

File input

Use with caution: available Web

File input allows files to be attached and/or uploaded. Use the single file variation for one file at a time, or the multiple file variation to include several files in sequence.

Overview

The file input component gives users a way to select and upload files. You have two options:

Single file input – Use when users need to upload one file at a time.
Multiple file input – Use when users need to upload several files in sequence.

Examples

Basic usage

Component variations

Required field

View va-file-input when required in Storybook

File type restrictions

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

Image files only

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

Maximum file size

View va-file-input with max file size in Storybook

Read-only state

View va-file-input in read only state in Storybook

Read-only with additional field

View va-file-input in read only state with additional inputs in Storybook

Header-style label variation

View va-file-input header label in Storybook

File uploading with progress indicator

An API must populate percentUploaded with a value to display the progress bar.

File input component showing a progress bar at 50% while uploading a document — File input showing upload progress. (Screenshot)

Error states

Missing required file

Wrong file format — Error message shown when the file doesn't meet requirements. (Screenshot)

Additional scenarios

File with an additional form input

Additional form inputs — File input used with additional form field to complete the upload process. (Screenshot)

File with an additional form input error

File form field error — Error message shown for general form field validation issues. (Screenshot)

Password-protected PDF prompt

Logic for detecting and decrypting PDF files is handled in a shared Platform utility. View Checking if an uploaded PDF is encrypted.

File input password prompt — User prompted to enter password for encrypted PDF file. (Screenshot)

Password error

File input field error — Error message shown when password is incorrect. (Screenshot)

Password success

Usage

When to use this component

Single file upload. When users need to attach or upload one file.
Multiple file upload. When users need to upload several files without additional form fields per file. If you need to ask for additional information with each file, use the Ask users for Files pattern instead.
Required documentation. When the upload is a required part of the form submission.
File validation. When you need to restrict file types or size for validation.

When to consider something else

Additional form fields with multiple files. If each uploaded file requires additional form fields, such as a document type selection or a description, use the Ask users for Files pattern instead. That pattern provides guidance on how to pair file inputs with additional fields in a multiple file upload flow.

How file inputs work at VA

Upload one file at a time. The file input component uploads a single file per interaction. People cannot select multiple files at once because:

Not everyone knows how to select multiple files in their OS file browser
Some mobile devices do not support selecting multiple files at once

When you need additional form inputs with each file, use the Ask users for Files pattern. For example, if each uploaded file requires a document type selection or a description, the pattern shows you how to structure file inputs with accompanying form fields. This approach works better on mobile devices overall.

For multiple file uploads, follow the Ask users for Files pattern and use the Multiple responses / List & Loop pattern to break up the file upload requests. This reduces cognitive load and improves the user experience.

Implementation best practices

Always pair with a clear label. The label should describe what file users need to upload (e.g., “Upload your discharge papers” not just “Upload file”).

Use hint text for restrictions. Clearly communicate any file requirements using hint text. For example:

Allowed file types: “PDF, JPG, or PNG only”
File size limits: “Maximum file size: 10 MB”
Any other requirements: “Must be in color and clearly legible”

Note: These are example hints and not actual limitations of the component.

Show upload progress when files upload to the server immediately. Display the Progress bar - Activity component if the upload happens automatically. Progress indication is not needed if the file uploads when the form is submitted.

Code usage

Web

Attributes and Properties

Property Attribute Type Default Description

accept accept string

A comma-separated list of unique file type specifiers.

disablePasswordSubmitButtonPattern disable-password-submit-button-pattern boolean false

When false, the component will render a “Submit password” button in addition to the password input field for encrypted files. When true, only the password input field will be rendered for encrypted files.

enableAnalytics enable-analytics boolean false

Emit component-library-analytics events on the file input change event.

encrypted encrypted boolean false

When true, displays a password field.

Note: This component does not check if a file is encrypted. For encryption checks, see: Checking if an uploaded PDF is encrypted

error error string

The error message to render.

headerSize header-size number

Optionally specifies the size of the header element to use instead of the base label. Accepts a number from 1 to 6, corresponding to HTML header elements h1 through h6. If not provided, defaults to standard label styling.

headless headless boolean false

DST only prop removes extraneous display for multiple file input

hint hint string

Optional hint text.

label label string

The label for the file input.

maxFileSize max-file-size number Infinity

Maximum allowed file size in bytes.

minFileSize min-file-size number 0

Minimum allowed file size in bytes.

name name string

The name for the input element.

passwordError password-error string

Error message for the encrypted password input

passwordSubmissionSuccess password-submission-success boolean null

Denotes if user submission of encrypted file password was successful. Use of this prop is required, unless disablePasswordSubmitButtonPattern is true.

percentUploaded percent-uploaded number null

Percent upload completed. For use with va-progress-bar component

readOnly read-only boolean false

Optionally displays the read-only view

required required boolean false

Sets the input to required and renders the (*Required) text.

statusText status-text string

Optional file status, ex: “Uploading…”, “Uploaded”.

uploadMessage HTMLElement null

Custom instructional message in the file input.

uploadedFile UploadedFile

Object representing a previously uploaded file. Example: { name: string, type: string, size: number}

value File

The value attribute for the file view element.

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.

vaFileInputError The event emitted when adding a file results in an error, e.g. exceeding max file size

vaPasswordChange The event emitted when the file input password value changes when `disablePasswordSubmitButtonPattern` is true.

vaPasswordSubmit The event emitted when the file input password is submitted.

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

Component checklist

Web Platform

90%

9 of 10 complete

Maturity

Guidance: Web

Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
Research: Web

VFS team conducted research on this component which is linked from this page.
Stability: Web

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: Web

Multiple teams have adopted this component.

Accessibility

While this component has been previously tested against older criteria, it has not yet been audited with the updated testing criteria.

Code assets

Variations: Web

Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Web

Component depicted in all responsive breakpoints.
Interactive states: Web

Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: N/A Web

All design attributes (color, typography, layout, etc.) are available as tokens.
Internationalization: N/A Web

Describes i18n attributes.

Visual assets

Variations: Web

Figma library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Web

Component designed to work in all responsive breakpoints.
Interactive states: Web

Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: N/A Web

All design attributes (color, typography, layout, etc.) are available as tokens.

Legend:

Complete
Incomplete
N/A Not applicable

Provide feedback

Share your feedback, report issues, or suggest improvements for the File input component. Your input helps us make the design system better for everyone.

Get immediate support in #platform-design-system for technical or urgent issues.
Share feedback about the File input component in the dedicated discussion thread.
Explore all feedback channels for additional ways to share your input.

Edit this page in GitHub (Permissions required)

Last updated: Apr 10, 2026