Skip to content

Shoppable Images

A shoppable image is a picture with your products in it, so shoppers can buy what they see. It suits any shop that photographs its products in use:

  • an outfit on a model (fashion: "shop the look", "complete the look"),
  • a furnished room or a laid table (homeware and furniture: "shop the room"),
  • a dish and its ingredients (food: "shop the recipe"),
  • a finished project and the tools and materials it needed (hardware, crafts),
  • a gift set or a bundle laid out flat.

The picture shows a marker (a hotspot) on each product, and the products are listed, numbered, with their name, the colour or finish pictured, the price and an Add button. The list follows the photo's shape: beside a portrait photo on a wide screen it is a column of compact rows; under a landscape photo, and under every photo on a phone or tablet, it is a strip of cards the shopper scrolls sideways. Tapping a hotspot scrolls the list (only the list, never the page) to its product.

Add opens a small size panel next to the product (a sheet from the bottom on a phone): a grid of sizes where a tap adds that size, or for jeans and chinos a waist and a leg length and then Add to basket. The product's thumbnail opens the same panel with a larger picture of the product, front and back where there is one, since a piece is often worn under another in the photo. The add happens without leaving the page and the panel says it was added, with Keep looking and View basket. A product that is sold out stays in its place in the list, greyed, marked "Out of stock". Without JavaScript, Add goes to the product page.

Each photo has a Full screen button (a click on the photo does the same), which opens the lookbook reader: every shoppable image on the page, one at a time, full screen, in page order. Text blocks on the page become pages of the reader too: the introduction just before the first picture becomes a cover (its heading over the first photo) and an introduction page, and a text block placed between two pictures becomes a chapter page. Each heading starts a new page, so a chapter's text block just before the first picture (after the page's own introduction) becomes the first chapter page. The shopper turns pages by swiping, with the arrow keys or the side buttons; the products of each photo sit in a strip along the bottom and open the same size panel. Zoom shows the photo at about two and a half times its size. The browser's Back button goes back one page at a time, and the close button (or Escape) closes the reader and leaves the page at the picture the shopper ended on. A link copied while reading (/p/lookbook#look-autumn-layers) opens the page scrolled to that picture; it never opens the reader by itself. A chapter's link is named after its heading (/p/lookbook#chapter-town) and scrolls to it in the same way. On a phone a landscape photo is cropped at its focal point when every hotspot still fits, and shown whole when one would be cut off.

So the markers don't hide the clothes or objects they point at, each one is a small frosted dot until a shopper points at it, or at its product in the list, when it grows into a numbered disc. On a touch screen, where there's no pointing, the numbers show all the time on smaller discs, so a shopper can match a marker to the list below the picture.

What a shoppable image holds

Part What it is
Title Shown over the products, e.g. "Autumn layers", "The reading corner", "Sunday roast"
Story Optional, a sentence or two under the title
Picture An image from the media library
Products Up to 20, in the order they're numbered. Each one can name the variant pictured: a whole variant (a tan bag in its only size), or some of its choices (the colour) with the rest left to the shopper (the size). Each can have a quantity ("2 pictured": two chairs, four jars) and a hotspot position
Links to category pages Optional category pages (/c/...) or collection pages (/collection/...), shown as "Shop Knitwear" links
Handle What a content block names it by, made from the title (autumn-layers). It stays the same when the site is copied to another environment, so blocks keep working
Show on the shop Off keeps it in the admin without showing it anywhere

How shoppers buy from it

Each product gets the simplest way to buy that is still right:

  • Add to basket when what's pictured is one thing to buy: a product without variants, or a variant with every choice made.
  • A grid of the choice left when the pictured variant leaves exactly one choice to make, usually the size: a tap on a size adds it, and sold-out sizes are greyed out and can't be chosen.
  • Two groups of buttons and Add to basket when exactly two choices are left, such as a waist and a leg length: a value with nothing in stock for the other choice made can't be chosen.
  • Choose options, a link to the product page, when more than one choice is left, or the product needs more than a quantity (gift cards, donations, menu items, appointments, any amount). The link opens the product page with what is pictured already chosen: ?v= for one variant, ?o=colourway:Oatmeal for a choice (the variant picker in Nova-family themes reads both).
  • Out of stock when nothing pictured can be bought.

Prices come from the catalogue when the page is shown. When the variants left cost different amounts the lowest is shown as "From £x"; a sale price shows with the was-price. Products that are disabled, or in a staff-only collection the shopper can't see, are left out and the others are renumbered. Stock is read for display and checked again by the basket. A block is kept for five minutes once drawn, so the sizes and "sold out" it shows can be up to five minutes behind; staff and shoppers who can see different collections never share a copy.

The block posts to the same /basket endpoint as the product page, so the basket's rules (stock, minimum and maximum quantities, a payment in progress) apply unchanged.

Showing one: the Shoppable image block

Add the Shoppable image content block (shoppableImage) wherever a picture should go:

Setting What it does
Picture (handle) The shoppable image to show. Several handles separated by commas (coast-walk, town-coat) show all of those pictures, in that order: a lookbook is quicker as one block per chapter than one block per picture, because the block fetches all its pictures' products and stock together
Use page context (useContext) On a product page, show the pictures that product is in ("complete the look"). On a category or collection page, show the pictures that link to it. The handle is then the picture shown when the page has none of its own
Heading (heading) The line over the title, e.g. "Shop the look", "Shop the room". Empty uses the shop's text for shoppableImage.eyebrow ("In this picture")
Most pictures (maxImages) With page context, how many to show, one under another (1 to 4)
Add to basket from the picture (quickAdd) Off shows only links to the products

The block goes under the page's content by default (bottomBanner), and under the product details on a product page (lowerBannerSlot). Set its page location to topBanner to put it above. It works on pages, collections, category pages (MerchandisingNode topBanner / bottomBanner) and product pages. For "complete the look" on every product page, put one block with Use page context on the product stereotype: pages of products in no picture show nothing.

The storefront text is in messages.properties under shoppableImage.* and can be changed per shop in Site Text.

Linking to a picture

Each picture on a page has a link target made from its handle, #look-<handle>, so a banner, a carousel slide or an email can link straight to it: /p/lookbook#look-autumn-layers opens the lookbook at that picture, its title clear of the header (themes set how far with --shoppable-anchor-offset). The handle stays the same when the site is copied to another environment, so the links keep working.

Themes

The block is one template, nova/extensions/shoppableImage/main.html, used by Nova and every theme layered on it (Atelier, Brock, Depot, Pop, Spec...). A theme changes its look through the --shoppable-* tokens in bdgr.css (corners, hotspot colours and sizes, title font and size, lines; --shoppable-hotspot-dot-size, --shoppable-hotspot-size and --shoppable-hotspot-touch-size set the resting dot, the numbered disc and the touch-screen disc); Atelier sets them to its square corners, display serif and glaze green. The rows and cards, the size panel and the reader have tokens of their own (--shoppable-row-thumb, --shoppable-card-width, --shoppable-sold-out-color, --shoppable-panel-bg, --shoppable-focus, and --shoppable-reader-* for the reader's backdrop, controls, panel, accent, focus ring and title font); Atelier's reader is ink with glaze and Instrument Serif titles. The hotspots, the layout and the size panel are run by js/extensions/shoppableImage/shoppable-image.js and the reader by shoppable-reader.js; without them the hotspots stay hidden, Add links to the product page and the numbered list still works.

In the admin

Catalogue > Shoppable images lists them with their picture, handle, number of products and how many are not placed on the picture. The editor:

  1. Choose picture opens the media library (search by title, alt text or tag).
  2. Add a product searches by name or SKU. Each product's variant groups get a list: pick the colour or finish pictured and leave the size on "Any (shopper chooses)".
  3. Place next to a product, then click the picture, to put its number there. Drag a number to move it, or focus it and use the arrow keys (Shift for bigger steps). Clicking the picture with nothing armed places the first product that has no number yet.

For agents (MCP)

shoppableImages (list, get by handle) and manageShoppableImages (save, delete). save with a handle the shop doesn't have creates one (it needs title, mediaId and items); with a known handle it changes only the fields given. items replaces the products: [{sku, options: {variantGroupCode: value}, quantity, x, y}], with x and y as percentages of the picture from its top-left corner. Upload or import the picture with manageMedia first, then place the shoppableImage block with manageExtensionConfig.

Copying a site and demo sites

Shoppable images travel with site data transfer in catalogue/shoppable-images.json. The import replaces the target's images, gives each a new id and points it at the imported picture; the handle and SKUs stay as they were, so blocks and products match without remapping. An image whose picture or products didn't arrive is skipped with a warning.

Demo sites declare them in their spec as shoppableImages (see dev-scripts/demo-sites/lib/shoppable.mjs): the picture file, the items as [sku, value pictured, {x, y, quantity}] and the pages to place them on.

Code

Part Where
Model ShoppableImage, ShoppableImageItem, ShoppableImageRepository (common, shoppable package), collection shoppableImages, by catalogueId
Service ShoppableImageService / ShoppableImageServiceImpl (commerce-core): validation, handles, the queries for product and category pages
Storefront view ShoppableImageViews builds ShoppableImageViews: prices, stock, how each piece is bought, picture sizes
Block ShoppableImageExtension (shoppableImage)
Admin ShoppableImageAdminController, templates/admin/shoppable/, js/admin-shoppable-images.js
MCP ShoppableImageTools
Transfer SiteTransferServiceImpl.importShoppableImages

Design decisions: Shoppable images.