Ask users for…

Files

Also known as: File upload

Usage

When to use this pattern

• Required documentation. When a user must upload a file in order to provide required documentation.

When not to use this pattern

• Don’t ask for a file if it does not affect service delivery. Only ask users to upload documents when it is absolutely necessary.

Examples

Asking for a single file

View a mock form example of a file upload

Asking for multiple files

Asking for additional information

Examples within a mock form

Examples of how each of these patterns work can be found in the Form library mock form in staging:

• Example asking for a single file
• Example asking for multiple files with no additional questions
• Example asking for multiple files with additional info (required multiple response flow)
• Example asking for multiple files with additional info (optional multiple response flow)

How to design and build

Layout details

Single file upload

Use the File input component along with the following content placed above it:

• Header that clearly describes what file to upload
• Instructions explaining what file(s) to upload and why they’re needed
• Bullet list of allowed file types and maximum file sizes

Important: Avoid allowing batch file uploads where users select many files at once in a single action (for example, selecting a whole folder or many files in one native file picker). These batch uploads are not mobile-friendly and can create user experience and technical issues. Instead, let users add files one at a time using repeated single file inputs or the multiple file upload pattern described below.

Multiple file upload

• If users only need to upload files and don’t need to answer separate questions about each one, use the multiple file upload pattern. This pattern lets users add files one at a time (not as a single batch selection) and review or remove each file before continuing.
• If users also need to provide additional information about each file, use the Ask users for multiple responses pattern with single file upload inputs.

Additional questions about the file

Within forms, ask questions about the file using separate form fields on the same page as the file upload component when possible.

This is especially helpful for multiple file uploads because users can review file details with each file.

• If you need to ask more than 2 questions, consider moving those questions to a separate page after file upload.
• If you use a single file upload outside a form flow, you can use the slot in the file input component to ask for additional information about the file.

How this pattern works

We’ve updated the File input component to encapsulate this pattern. Upgrade to the latest file input component to get the current functionality.

• List allowed file types and sizes above the File input component. This helps prevent errors. Most VA forms accept PDF, JPG, JPEG, and PNG files.
• Provide clear instructions. Tell users exactly what document to upload and why it’s needed for their application.
• Validate file uploads and provide clear error messages. Review feedback messages in the Messages dictionary for file upload success and error messages.

Code usage

Components used in this pattern

• File input
• Modal

Forms library validation

The forms-system validates every file before upload for:

• Mime-type and file extension match (e.g., prevents my-pdf.png)
• UTF encoding to ensure proper file handling
• PDF encryption - The forms library detects if a PDF is encrypted and, if so, prompts the user for a password. The password is required to send the file to the backend for decryption before form submission.

Note: If validation fails, an error message is sent to the component and displayed to the user.

File submission

The pattern handles the submission to the endpoint and returns a response if there is an error.

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.

• Consider the mobile experience. Avoid using words like “scan” or “convert” in the file upload instructions.

If your team needs help customizing the content of the component to address upload problems and user errors, contact the Content and IA centralized team for support.

Accessibility considerations

• Do not italicize file type and size help text. Long strings of italicized text can be difficult to read for some users with low vision or reading disabilities.
• Ask for confirmation when deleting files. Destructive actions like deleting files should require two steps by users — the initial button click, and then a confirmation. This helps prevent users from accidentally deleting a file with an unintentional click, and provides an extra prompt for screen reader users and screen magnification users who might not see the visual change when a file is removed.
• Provide clear error messages. When file uploads fail, ensure error messages clearly explain what went wrong and how to fix the issue.