Drop zone
The drop zone component lets users upload files by dragging and dropping the files into an area on a page, or activating a button.
Props
No props found for this component, run `yarn gen:docs` to generate component meta first.
Slots
No slots found for this component, run `yarn gen:docs` to generate component meta first.
Events
Best practices
Drop zone
Drop zones should:
- Inform merchants when the file(s) can’t be uploaded:
- When possible, use validation errors on drag to detect and explain things like file size limits or file types accepted.
- Use the banner component with a critical status to communicate errors that happen on the server.
- Provide feedback once the file(s) have been dropped and uploading begins.
- For convenience, allow files to be dropped anywhere on the page by enabling
dropOnPage. - Provide a file upload button to allow merchants to select files for upload in a traditional way. Do this by using the
DropZone.FileUploadsubcomponent.
Validation errors
The drop zone component validates file type by default. File types you wish to accept can be defined by editing the accept property. This component also accepts custom validations using the customValidator property. When validation fails, the component sets itself to error mode.
Content guidelines
Client-side validation error messages
Client-side validation errors give instant feedback.
Validation error messages should be:
- Explicit: help merchants understand why their file can’t be uploaded and what they should change to successfully upload their file
- In sentence case: capitalize only the first word in the message
- Concise: use simple, clear language that can be read at a glance. For example:
File size must be less than 20MB
File type must be .gif, .jpg, .png or .svg
Server-side upload error messages
Server-side upload errors give feedback after file submission.
Upload error messages should:
- Be displayed as a banner with a critical status
- Show the name of the file(s) that were not uploaded successfully
- Describe why the file(s) couldn’t be uploaded and what merchants should change to upload their file successfully, as seen below
The following images couldn’t be uploaded:
* “keep-it-real.png” is too large. Try a file size less than 20MB.
* “realer-than-real.zip” is not supported. File type must be .gif, .jpg, .png or .svg.
* “so-so-real.png” was interrupted due to weak network connection, [retry upload](#)Drop zone file upload
Use file upload with the drop zone component to let merchants select files for upload in a traditional way.
File upload properties
| Prop | Type | Description | Default |
|---|---|---|---|
| actionTitle | string | String that appears in file upload | 'Add file' |
| actionHint | string | String that appears in file upload | 'or drop files to upload' |
Related components
- To provide context to upload errors when they occur, use the banner component
- To provide feedback during file upload, use the spinner component
Accessibility
The drop zone component builds on the native HTML <input type="upload"> element. It includes a visual<button> as well as a drag and drop area that can receive keyboard focus.
Keyboard support
To upload a file with the keyboard, merchants can interact with the drag-and-drop region.
- To give the input keyboard focus, use the tab key (or shift + tab when tabbing backwards)
- To activate the input, use the enter/return or space keys