Building a shoppable lookbook

This walkthrough builds a shoppable scene from a fresh install, then explains exactly how it behaves on the storefront.

1. Create the lookbook

1. Go to Lookbooks → Add New.
2. Give it a title (used internally and as the image alt text).
3. Set the Featured image, the photo your products live in.

2. Find your product IDs

Each hotspot needs a WooCommerce product ID. Under Products, open a product; the ID is the post=456 value in the URL. Note the IDs of every product visible in your image.

3. Pin the products

In the Shoppable hotspots box, add one row per product:

1. X %, horizontal position from the left (0-100).
2. Y %, vertical position from the top (0-100).
3. Product ID, the product to pin.

Use + Add hotspot for more rows; Remove drops one (the last row is kept rather than leaving an empty table). There is no in-editor preview, so start each marker near 50/50, publish, and adjust the percentages after checking the storefront.

4. Set presentation defaults

Under WooCommerce → Lookbook, decide globally whether to show the price and the add-to-cart link (with an optional label override). These apply to every lookbook, see Configuration.

5. Embed it

Find the lookbook’s ID by editing it (the post=123 value in the URL), then place the shortcode in any page or post:

[lookbook id="123"]

The shortcode is the only embed method, there is no Lookbook block. The same ID can be reused on any number of pages; each renders the same image and hotspots.

6. How the storefront behaves

Each hotspot renders as a numbered <button> absolutely positioned at its X/Y percentage. Activating one opens a product card:

• The card uses the native Popover API (popover + popovertarget), so the browser handles open, close, click-outside dismiss and Escape with no script.
• The bundled script only positions the open card near its marker, centred below it, flipped above when there is no room, and clamped to the viewport, and repositions it on resize, so the card never covers the product or runs off-screen.
• The card shows the product thumbnail and title (both linking to the product page), the live price (if Price is on), and an add-to-cart link (if Add to cart link is on). The add-to-cart link only appears for a purchasable, in-stock product; otherwise the card shows a View product link instead.

Keyboard and screen-reader behaviour

• Markers are real buttons: Tab reaches each one, Enter/Space opens its card.
• Each marker carries an aria-label like View Linen Shirt and aria-haspopup="dialog"; the visible content is just the number, with the full label as screen-reader text. Screen-reader users hear the product name, not “button”.
• The card is a role="dialog" labelled by the product name.
• The focused marker shows a visible focus-visible outline, so keyboard users always see where they are.

Older browsers (no Popover API)

If the browser lacks the Popover API, the script supplies a fallback: it toggles the card with the marker, tracks aria-expanded, closes others when one opens, and closes on Escape or a click outside. With JavaScript fully disabled the markers do nothing harmful and the image and page are unaffected.

When a hotspot is skipped

A hotspot whose product is deleted, unpublished, or not a valid product is dropped at render, no marker is drawn. If every hotspot is skipped, or the lookbook has no featured image, or the master switch is off, the lookbook renders just the image or nothing at all. You can configure a scene gradually without ever showing a broken marker.

Where Lookbook fits

• Fashion outfits, pin each garment in a styled photo.
• Room sets, pin furniture and decor in an interior shot.
• Gift guides, pin every item in a curated flat-lay.
• Recipe shots, pin the ingredients in a finished-dish photo.

Extending the output (developers)

Lookbook registers no shortcodes other than [lookbook] and exposes two settings-screen hooks for add-ons (used by Lookbook Pro):

// Add a settings card inside the same form, after the core cards.
add_action( 'lookbook_admin_settings_after_cards', function ( array $settings, string $option ): void {
    // $option is 'lookbook_settings'. Name fields as $option . '[my_key]'
    // so they submit under the shared option.
}, 10, 2 );

// Keep your own keys when the core sanitiser cleans the option on save.
add_filter( 'lookbook_sanitize_settings', function ( array $clean, array $raw ): array {
    $clean['my_key'] = ! empty( $raw['my_key'] );
    return $clean;
}, 10, 2 );

The sanitiser rebuilds the option from a fixed set of keys, so any key you add through lookbook_admin_settings_after_cards must be re-attached in lookbook_sanitize_settings or it is dropped on save.