Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

DropZone

The DropZone component allows file uploads through drag-and-drop functionality into a designated area on a page, or by activating a button. At present, the DropZone component does not offer image upload preview capabilities. The use of object URLs directly in an image component is not possible due to the extension and host operating on separate domains.

Any element focused within the DropZone component, including child elements such as the 'Add file' button, will initiate the file selector when the Enter or Spacebar key is pressed.

Support
Targets (50)

Supported targets

Anchor to DropZonePropsDropZoneProps

Anchor to accept
accept
string

A string representing the types of files that are accepted by the dropzone. 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 left empty, the dropzone will accept all files.

Learn more about the accept attribute.

Anchor to accessibilityLabel
accessibilityLabel
string

A label that describes the purpose or contents of the item. When set, it will be announced to users of assistive technologies and will provide them with more context.

Anchor to disabled
disabled
boolean

Whether the drop zone 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 drop zone is styled with error indicators.

Anchor to id
id
string

A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.

Anchor to label
label
string

The text displayed as the field label, which identifies the purpose of the drop zone to users.

Anchor to multiple
multiple
boolean
Default: false

Defines if the user can select or drop multiple files at once.

Anchor to name
name
string

An identifier for the field that is unique within the nearest containing Form component.

Anchor to onDropRejected
onDropRejected
(files: File[]) => void

A callback fired when rejected files are dropped. Files are rejected based on the accept prop.

Anchor to onInput
onInput
(files: File[]) => void

A callback fired when files are dropped or selected.

Learn more about the drop event.

Anchor to required
required
boolean

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 prop.

Anchor to ExamplesExamples

Anchor to DropZoneDropZone

DropZone

An image showcasing the DropZone component with a button to add files with error and dragged over states.

DropZone

import {
reactExtension,
DropZone,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return <DropZone accept="image/*" />;
}
import {DropZone, extension} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const dropZone = root.createComponent(DropZone, {
accept: 'image/*',
});

root.appendChild(dropZone);
});

Anchor to Best practicesBest practices

  • Restrict accepted file types: Use the accept property to limit file uploads to valid formats like image/* or application/pdf.
  • Set a minimum size: Keep the drop zone to at least 100px by 100px to prevent truncated text and spacing issues.
  • Handle rejected files: Use the onDropRejected callback to display clear error messages when files don't match the accepted type.
  • Include a click-to-browse option: Drag and drop doesn't work on mobile devices. Include an option to select files manually.

Anchor to LimitationsLimitations

  • File storage must be implemented separately. Use metafields through the Metafields API to store references to uploaded files.
Was this page helpful?