Choose a version:

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.

Support

Targets (29)

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 accept accept string 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 (such as .jpg, .pdf, .doc)

A valid MIME type string with no extensions

If omitted, all file types are accepted.
Anchor to accessibilityLabel accessibilityLabel string: 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 disabled disabled boolean Default: false: Whether the field is disabled, preventing any user interaction.
Anchor to error error string: An error message displayed below the field to indicate validation problems. When set, the field is styled with error indicators and the message is announced to screen readers.
Anchor to id id string: A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
Anchor to label label string: The text displayed as the field label, which identifies the purpose of the field to users. This label is associated with the field for accessibility and helps users understand what information to provide.
Anchor to multiple multiple boolean Default: false: Whether multiple files can be selected or dropped at once.
Anchor to name name string: The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form.
Anchor to required required boolean Default: 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 error property.
Anchor to value value string 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 change change <typeof tagName>: A callback fired when the drop zone value changes.

Learn more about the change event.
Anchor to droprejected droprejected <typeof tagName>: A callback fired when files are rejected based on the accept prop.
Anchor to input input <typeof tagName>: A callback fired when the user inputs data into the drop zone.

Learn more about the input event.

CallbackEventListener

A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.

(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null

CallbackEvent

An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}

Examples

<s-drop-zone accept="image/*"></s-drop-zone>

Preview

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.

Was this page helpful?

Drop zone

Supported targets

Supported targets

Anchor to propertiesProperties

Anchor to eventsEvents

CallbackEventListener

CallbackEvent

Preview

Examples

Code

Default

Anchor to best-practicesBest Practices

File storage

Mobile

Minimum size