File picker usage guidelines

Caution

This component is currently in an unstable state and may undergo significant changes in future releases.

File pickers allows users to pick a file from their device.

When to use

• When users need to submit one or more files as part of a task or process.
• To upload documents, images, templates, or other user-generated content.

When not to use

• When the file or information is already available in the system (i.e., reuploading a template that is already stored)

Usage

Preview

Avatar

Choose file

No file selected

Choose a photo to use as your avatar

Code

import { UNSTABLE_FilePicker as FilePicker } from '@cimpress-ui/react';

export default function Demo() {
  return <FilePicker label="Avatar" description="Choose a photo to use as your avatar" />;
}

Formatting and layout

Placement

File picker should be placed near the data or task that it is related to. If it is part of a form it should follow the same structure as other input elements, and if it’s standalone it should be close to the preview area.

Spacing

• The paddings or spacing for the trigger element (button) should not be changed
• Place at least 16px space between the file picker component and other inputs or elements in the form.
• When using a preview box, the file picker component should follow the same rules as in forms.

Content writing

Label

• The label should clearly indicate what users are expected to upload.
• Do use a short description of just one or two words for the label such as “Product photo”.
• Do not format labels in the form of a question such as “What photo do you want to use?”
• Do not include verbs in your label such as “Add a product photo”.

Description text

• Do provide description text whenever the label might not be enough context for a user to understand the purpose of the file picker.
• Do not provide unnecessary description text when the purpose of the file picker is obvious.
• Do write clear and concise description text. Text should be limited to one sentence.
• End the description text with a period or equivalent punctuation mark. This helps screen reader users understand where the description ends, and it improves readability for all users.
• If there are any requirements, be specific and clear about them (“Max 10MB • JPG or PNG only”).

Error text

• Do provide clear and concise error messaging.
• Do explain the issue and let the user know what they need to do to resolve it. Error messages should always provide users with a solution or a path to resolving the error.
• Error messages should use language that is easily understood rather than complex technical terms.
• End the error message with a period or equivalent punctuation mark. This helps screen reader users understand where the error message ends, and it improves readability for all users.

Behaviors

Validation

• The validation should happen before upload and it should indicate the accepted file types, size, and number of files before upload.
• The error message should clearly highlight the failed validation criteria.