Media

The media library at Catalog → Media holds every image for your business: "All images for this business. Uploads are optimized automatically." Products do not own their images; they reference images from this shared library. That distinction matters for deleting: removing an image from a product keeps it in the library, while deleting it from the library removes it everywhere.

Upload images#

1. Click the dashed Upload images tile (or drag files anywhere onto the image grid).
2. Pick one or more files. Only JPEG, PNG, WebP, and AVIF images are accepted.

Uploads are optimized automatically on the server. Alt text is filled in for you from each filename: the extension is stripped and dashes and underscores become spaces (so red-garden-chair.jpg becomes "red garden chair"). You are never asked for alt text at upload time; edit it afterwards.

A successful batch shows "{count} images uploaded". If some files in a batch fail, the rest still upload and the toast reports "{ok} uploaded, {failed} failed".

Find images#

The search box ("Search by filename or alt text") filters the grid as you type, matching on filename or alt text. Each tile shows the image, its filename, and its alt text (an em dash when empty). The grid loads 100 images at a time; click Load more to fetch the next page. The library is a flat grid: there are no folders, tags, or bulk operations.

Edit an image's details#

Hover over a tile and click the pencil icon to open the Image details sheet. It shows the read-only Filename, Type, and Size, plus an editable Alt text field. Change the text and click Save (the button enables only once the text actually differs); saving an empty field clears the alt text. A "Alt text saved" toast confirms it.

Alt text lives on the media record itself, so a change applies everywhere the image is used, including every product it is attached to.

Delete an image#

Hover over a tile and click the trash icon. The confirmation warns: "Delete image?" / "The image is removed from storage and from any products using it." This is the destructive one: confirming removes the file from storage and detaches it from every product at once.

Product images#

Each product's detail page has an Images card for the images attached to that product. Its hint sums up the model: "Drag to reorder. The first large image is the featured image."

Attach images to a product#

• Add images: the dashed tile opens a file picker (same formats: JPEG, PNG, WebP, AVIF; multiple files), or drop files onto the card. Each file is uploaded into the shared media library and then attached to the product.
• Choose from library: opens a dialog with a searchable grid ("Search media", Load more pagination) of library images not already on the product. Click an image to attach it; the dialog closes with a "1 image added" toast.

Featured image and ordering#

The featured (primary) image renders as the large 2x2 tile shown first and carries a Primary badge. To change it, hover over another image and click the star (Set as featured); "Featured image updated" confirms it.

Drag the other thumbnails to reorder them (keyboard reordering works too); "Image order saved" confirms each change. The featured image itself cannot be dragged.

Per-image actions#

Hovering over a product image reveals:

• Set as featured (star): make this the primary image.
• Edit alt text (pencil): a popover with an Alt text input that saves when you leave the field. This edits the shared media record, so the new alt text applies everywhere the image is used, not just on this product.
• Remove image (X): detaches the image after confirming "Remove image?" / "This removes the image from the product. It stays in your media library."

Click any thumbnail to open a lightbox with Previous/Next buttons, arrow-key navigation, and an "n/total" counter.

Configurator choice images#

For made-to-measure products, each option choice has an Images dialog (opened from the Option groups card) that picks images from the same library. Click images to select or deselect them; selected images get a numbered badge, and that selection order is the order they are saved and shown in. Click Save images to persist the selection ("Images saved.").

Storefronts receive these images through the product API; see the products API reference.