Media

Product media is managed from the product page. The same upload flow is used for product images, option swatches, and storefront billboards.

Product media limits

Up to 18 images or videos per product.
The first item is the cover image.
Images and videos can be reordered by dragging.
Each item can have alt text for accessibility and SEO.

Removing a media item from a product removes the association. Deleting the media item also removes the stored object from the configured storage provider. Deletion cannot be undone.

Upload media

Open a product and find the Media section.
Select Upload Media or drag files onto the drop zone.
Wait for each upload to finish.
Drag the items into the order you want.
Set the cover image.
Add alt text to every image.

Uploading more than 18 items is rejected, so remove unused media before adding more.

Link media to options

If a product has options such as Color, you can link media to specific option values:

Open the media item's actions.
Choose Link to options.
Select the option values that should show this image.

On the storefront, the product gallery updates when the customer selects a swatch or value.

Option media is linked by value. Renaming or removing an option value unlinks its media, so review the option impact dialog before saving.

Storage providers

Product media can be stored in:

Cloudinary — the default.
S3-compatible storage — AWS S3, Cloudflare R2, SeaweedFS, RustFS, or another compatible service.

Local development uses Cloudinary by default or SeaweedFS when STORAGE_PROVIDER="s3". See Storage for the configuration details.

Billboards

Collection detail pages can include a billboard carousel:

Upload a JPG or PNG up to 1 MB.
Add alt text.
Reorder or delete slides.
Billboards appear on the storefront homepage for the selected collection.

Troubleshooting

Upload fails: check the storage provider credentials and the maximum file size for the provider.
The image is missing on the storefront: confirm the media URL is publicly reachable and that S3_PUBLIC_URL_BASE or the Cloudinary configuration matches the URL stored in the database.
The gallery does not change with the option: verify that the media is linked to the correct option value.