Usage guidelines outline how the component should and shouldn’t be used in different user interface contexts.
When to use
- To let users upload a single file or multiple files by using the native file picker or by dragging and dropping
- In forms, amongst other fields or inputs
- To upload a single file in a Dialog or Onboarding Dialog
When not to use
- Avoid using it in a dialog when multiple files are uploaded, as uploaded files stack vertically (use the File Upload component in a page or Drawer instead)
Best practices
Do use “Upload” as the verb in the component label. For example, use “Upload files” or “Upload package” to communicate what the user can do.
Don’t solely use the verb “Upload” in the component label without a contextual noun.
Do use helper text to indicate file limitations. Provide users with this information to help avoid errors, like uploading an incompatible file type or too many files.
Don’t “surprise” users with an error by failing to include helper text to indicate file limitations upfront.
Do truncate the file name at the end if it’s too long.
Don’t wrap file names onto multiple lines.
Do display an error message to clearly communicate why one or more files failed.
