Drop zone
The drop zone component lets users upload files through drag-and-drop or by clicking to browse. Use for file uploads such as images, documents, or CSV imports.
The component provides visual feedback during drag operations and supports file type validation through the accept property. Rejected files trigger the droprejected event for custom error handling.
Supported targets
- purchase.
checkout. actions. render-before - purchase.
checkout. block. render - purchase.
checkout. cart-line-item. render-after - purchase.
checkout. cart-line-list. render-after - purchase.
checkout. contact. render-after - purchase.
checkout. delivery-address. render-after - purchase.
checkout. delivery-address. render-before - purchase.
checkout. footer. render-after - purchase.
checkout. header. render-after - purchase.
checkout. payment-method-list. render-after - purchase.
checkout. payment-method-list. render-before - purchase.
checkout. pickup-location-list. render-after - purchase.
checkout. pickup-location-list. render-before - purchase.
checkout. pickup-location-option-item. render-after - purchase.
checkout. pickup-point-list. render-after - purchase.
checkout. pickup-point-list. render-before - purchase.
checkout. reductions. render-after - purchase.
checkout. reductions. render-before - purchase.
checkout. shipping-option-item. details. render - purchase.
checkout. shipping-option-item. render-after - purchase.
checkout. shipping-option-list. render-after - purchase.
checkout. shipping-option-list. render-before - purchase.
thank-you. announcement. render - purchase.
thank-you. block. render - purchase.
thank-you. cart-line-item. render-after - purchase.
thank-you. cart-line-list. render-after - purchase.
thank-you. customer-information. render-after - purchase.
thank-you. footer. render-after - purchase.
thank-you. header. render-after
Supported targets
- purchase.
checkout. actions. render-before - purchase.
checkout. block. render - purchase.
checkout. cart-line-item. render-after - purchase.
checkout. cart-line-list. render-after - purchase.
checkout. contact. render-after - purchase.
checkout. delivery-address. render-after - purchase.
checkout. delivery-address. render-before - purchase.
checkout. footer. render-after - purchase.
checkout. header. render-after - purchase.
checkout. payment-method-list. render-after - purchase.
checkout. payment-method-list. render-before - purchase.
checkout. pickup-location-list. render-after - purchase.
checkout. pickup-location-list. render-before - purchase.
checkout. pickup-location-option-item. render-after - purchase.
checkout. pickup-point-list. render-after - purchase.
checkout. pickup-point-list. render-before - purchase.
checkout. reductions. render-after - purchase.
checkout. reductions. render-before - purchase.
checkout. shipping-option-item. details. render - purchase.
checkout. shipping-option-item. render-after - purchase.
checkout. shipping-option-list. render-after - purchase.
checkout. shipping-option-list. render-before - purchase.
thank-you. announcement. render - purchase.
thank-you. block. render - purchase.
thank-you. cart-line-item. render-after - purchase.
thank-you. cart-line-list. render-after - purchase.
thank-you. customer-information. render-after - purchase.
thank-you. footer. render-after - purchase.
thank-you. header. render-after
Anchor to propertiesProperties
- Anchor to acceptacceptacceptstringstringDefault: ''Default: ''
A string representing the types of files that are accepted by the drop zone. This string is a comma-separated list of unique file type specifiers which can be one of the following:
- A file extension starting with a period (".") character (e.g. .jpg, .pdf, .doc)
- A valid MIME type string with no extensions
If omitted, all file types are accepted.
- Anchor to accessibilityLabelaccessibilityLabelaccessibilityLabelstringstring
A label that describes the purpose or contents of the item. When set, it will be announced to buyers using assistive technologies and will provide them with more context.
- Anchor to disableddisableddisabledbooleanbooleanDefault: falseDefault: false
Disables the field, disallowing any interaction.
- Anchor to errorerrorerrorstringstring
Indicate an error to the user. The field will be given a specific stylistic treatment to communicate problems that have to be resolved immediately.
- Anchor to idididstringstring
A unique identifier for the element.
- Anchor to labellabellabelstringstring
Content to use as the field label.
- Anchor to multiplemultiplemultiplebooleanbooleanDefault: falseDefault: false
Whether multiple files can be selected or dropped at once.
- Anchor to namenamenamestringstring
An identifier for the field that is unique within the nearest containing form.
- Anchor to requiredrequiredrequiredbooleanbooleanDefault: falseDefault: false
Whether the field needs a value. This requirement adds semantic value to the field, but it will not cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the
errorproperty.- Anchor to valuevaluevaluestringstringDefault: ''Default: ''
A string that represents the path to the selected file(s). If no file is selected yet, the value is an empty string (""). When the user selected multiple files, the value represents the first file in the list of files they selected. The value is always the file's name prefixed with "C:\fakepath", which isn't the real path of the file.
Anchor to eventsEvents
Learn more about registering events.
- Anchor to changechangechangeCallbackEventListener<typeof tagName>CallbackEventListener<typeof tagName>
Callback when the user has finished selecting a file or files.
- Anchor to droprejecteddroprejecteddroprejectedCallbackEventListener<typeof tagName>CallbackEventListener<typeof tagName>
Callback when rejected files are dropped. Files are rejected based on the
acceptprop.- Anchor to inputinputinputCallbackEventListener<typeof tagName>CallbackEventListener<typeof tagName>
Callback when the user makes any changes in the field.
CallbackEventListener
(EventListener & {
(event: CallbackEvent<TTagName, Event> & TData): void;
}) | nullCallbackEvent
TEvent & {
currentTarget: HTMLElementTagNameMap[TTagName];
}Preview
Examples
Code
Default
<s-drop-zone accept="image/*"></s-drop-zone>
Anchor to best-practicesBest Practices
File storage
File storage for uploads must be implemented separately. Metafields and the corresponding Checkout API or Customer Accounts API can be utilized to store references to files alongside the relevant objects.
Mobile
Remember that the drag and drop feature won’t be effective on mobile devices. Adding a button can offer additional context and guide users through the next steps.
Minimum size
To prevent cut-off text and spacing issues, the minimum size of a Dropzone should be 100px by 100px.
