Skip to content
Change the site theme

File Picker

Design assets pending
Peer review pending

A File Picker is a form element used to upload files.


Guidelines page anchor

About File Picker

About File Picker page anchor

Use a File Picker when users need to upload a document in a form flow. The File Picker allows any type of file by default, but the desired file type can be specified using the accept prop. This is a native HTML file picker, <input type="file" />, so there's currently no drag-and-drop or multiple attachments functionality. Read more about the native file picker on MDN.(link takes you to an external page) The input is hidden visually, but still appears in the DOM, so that we're able to apply custom styles in an accessible way.

  • Include a visible Label on all form fields.
  • Each label must use the htmlFor prop that equals the id of the associated input.
  • Provide clear identification of required fields in the label or at the start of a form. If you use the required field indicator, include the form key at the start of the form.
    • Use the required prop to programatically indicate they are required to browsers.
  • Include inline error text with the error icon on any field that errors to make it visually clear that the field changed. You can also use the "error" variant of Help Text.
  • If the File Picker has associated help text or error text, include the aria-describedby prop on the File Picker. This should match the id of the help or error text.

The File Picker component should include the base File Picker, along with supporting elements to compose an input field that gives users the context they need to successfully complete it.

  • Label — A label should be included for every form field and provide a short title for its associated input.
  • Required field indicator — In a form where there are fewer or as many required fields as optional, use a required indicator to show users which fields are required to be filled out.
  • Help text — Text that's placed below the field to help users prevent an error and describe what makes the form field successful. If you're using the accept prop, specify the file type using Help Text.

Accessibility insight

Make sure to connect the Label to the File Picker. This is done with the htmlFor prop on the label, and the id prop on the File Picker. Those two need to match.

If the File Picker has any associated help text, it should also use the aria-describedby prop that equals the id of the help text. This ensures screen readers know the help text ties directly to the File Picker.

To internationalize a File Picker, simply pass the i18nNoSelectionText prop with the translated string. Because the FilePickerButton is compositional, you already pass the button text as children.

Labels should clearly describe the object being requested. They should be concise and descriptive, not instructional. To do this:

  • Use help text to provide instruction if needed. For example, don't use "Upload an image in the form of a jpeg or png" as label text. Instead, use "Profile photo" as a label and "Upload an image file" as help text.
  • Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".

Give users enough information in help text to prevent upload and file type errors. Keep it concise and scoped to information that will help with validation.

Validate form fields on form submission.

Validating a form field when the user leaves the current field (on blur) can be helpful to check for syntax errors. However, this can be frustrating to users who tab through controls to navigate a page, and to screen reader users, who might not be able to detect that an error occurred on blur.

Don't prevent form submission by disabling the submit button. An error message can give more information than a disabled button can to help users figure out which fields are invalid.

Use inline error text to explain how to fix an error.

Ideally, help text should have enough information to help users prevent errors. If HelpText is already on a form field, change it to variant=“error” and add error copy before the original help text copy.

Error text should:

  • Be actionable. Explain how to fix an error and if reasonable, why it happened so that it might also be prevented in the future.
  • Be concise and simple, maybe even more than normal. Avoid jargon. Try to keep error text to 2 sentences or fewer.
  • Use the passive voice for input errors to avoid placing blame on the user. For example, "A friendly name is required."
  • Use the active voice for system errors. For example, "Our systems are currently down. Please contact our support team."


Installation page anchor
yarn add @twilio-paste/file-picker - or - yarn add @twilio-paste/core
import {FilePicker, FilePickerButton} from '@twilio-paste/core/file-picker';
import {Label} from '@twilio-paste/core/label';
import {HelpText} from '@twilio-paste/core/help-text';
const MyFilePicker = () => (
<Label htmlFor="foo" required>
Profile photo
<FilePicker id="foo" required aria-describedby="foo_text">
<FilePickerButton variant="secondary">Choose a file</FilePickerButton>
<HelpText id="foo_text">Upload an image</HelpText>

All the valid attributes for Button are supported including the following props:

variant?ButtonVariantsButton variant used for the FilePickerButton. Recommended variant is 'secondary'.'primary'
element?stringOverrides the default element name to apply unique styles with the Customization Provider.'FILEPICKER_BUTTON'
childrenReact.ReactNodeThe text displayed on the FilePickerButton. Recommended for English is "Choose a file".null
accept?stringSpecify the desired file type. Note: file type should still be validated server-side, as this prop is not a complete validation. Read more about the accept prop(link takes you to an external page)null
childrenReact.ReactElement<FilePickerButton />null
disabled?booleanDisables the File Picker.false
required?booleanSets the File Picker as required.false
i18nNoSelectionText?stringThe text string displayed when no files are selected.'No file uploaded'
element?stringOverrides the default element name to apply unique styles with the Customization Provider.'FILEPICKER'
onChange?(event: React.MouseEvent<HTMLElement>)Function will run when the uploaded file changesnull

Black lives matter.