Anatomy
- Drop zone: (Optional) Designated area for users to drop their files
- Illustration: (Optional) A visual element that communicates the file upload action, usually representing files or folders
- Label: The main instruction or message guiding the user (e.g., “Drop files here to upload”)
- Actions: Interactive buttons such as Browse files to open the file selector dialog
- Hint message: (Optional) Secondary text clarifying accepted file formats or size limits
- Error message: Validation message displayed when a file does not meet the requirements
Usage Guidelines
When to use this component
Uploading or updating a single file
Use the File Upload component when users need to upload or update a file, either through drag-and-drop or by manually selecting them. Typically, this requires a single file upload with format restrictions (e.g., .png or .jpg).
Submitting multiple documents
Use the drop zone variant when users need to upload several files at once, (e.g., medical records, contracts, or ID documents). This scenario supports efficiency and gives users flexibility.
Uploading files as the main task
Use the drop zone version when uploading is the primary purpose of the screen or section.
This ensures the drag-and-drop area is visually clear and supports the main CTA (e.g. locating multiple files).
Uploading files as part of a form
When File Upload is just one step inside a form, use the default or icon button version alongside other inputs.
Previewing the uploaded file is not required in this context, clarity and consistency matter more.
Compact file upload trigger
Use the icon button variant when the File Upload needs to fit in a small area and no extra context (illustration, label, or hints) is required. This is ideal for inline uploads, toolbars, or chats where space is limited.
When not to use this component
- Don't use File Upload for simple data input. Instead, use input fields or other form components unless file formatting is required
Best Practices
Labels
In both variants, labels help us define the context in which a file upload is required, or how to proceed to succeed.
Labels should always be present, except for those cases where the context and elements that surround the input make it clear what data is needed or how to proceed (e.g. "Upload a file" button as a secondary action in a list). In those cases, the button label will be read by screen readers anyway.
Use labels that are short, descriptive, and support the action of the button.
Make sure not to duplicate information, if the label is not needed, it can be hidden.
Triggers
You can trigger a File Upload using an icon button or a button. Make sure you follow these components' guidelines at all times.
Use the icon button in the default variant when placing a File Upload in small places and if no other information is needed.
Do not use an icon button when displaying the dropzone variant or when there's enough space for the action to be labeled. Use a button instead.
Hint & errors
Like in any other input component, hints and error messages provide additional directions to support the component function in an accessible manner.
Use hints to provide useful information about the required input, for instance, accepted file types.
Do not duplicate information. If an error message is repeating the hint, rephrase the error to be more specific (E.g. Your file is not in an accepted format) or hide the hint.
General Component Behaviors
Width
File Upload has no min. or max. widths for its Default variant. However, for its drop zone variant, the min-width is 300px. In this case, if the container is larger than 300px, it will fill out the available width. If, on the other hand, the container is smaller, the Default variant should be used.
Content alignment and position
The alignment of content within the File Upload depends on its variant. If the default variant is used, the content is left-aligned and its position will depend on each scenario. If the drop zone variant is used, the content is center-aligned, and the entire component should be centered vertically and horizontally within its container.
Drag-and-drop interaction
Users can drag one or more files into the upload area. If supported, the files will be accepted and processed. When dragging files, the state of the drop zone will change to “dragover”, highlighting the area where users can drop their files.
States
Default
Dragover
Variants
Default
The default variant is simplified and left-aligned, without an illustration.
It is designed to be used within forms or alongside other inputs, where File Upload is just one part of the task.
Drop zone
The drop zone variant is centered and may include an illustration. It should be used when File Upload is the main purpose of the screen or section, making the drop area highly visible and engaging.
This variant also supports both single and multiple file uploads.
Content Guidelines
File Upload is a component that leaves little room for text, as it is an interactive element of the interface. Therefore, all of its content must be short, concise, and clear for users. A user should be able to quickly see the component and know what to do next.
Title
- The title should be short and descriptive, explaining the most important piece of information.
- When possible, communicate the main message using just the title.
- It is advisable to not exceed 50 characters
Actions
- They should be 3 words max and describe what can a user expect after clicking them.
Hint messages
- Hint messages should guide the user on how to succeed in their actions.
Error messages
- Error messages should explain what went wrong and how to fix it.
For further information, see the Content Styleguide.
Known Gaps
- Possible component enhancements:
- Guidelines on how to display the file upload process