Rendering banners with the SDK

Overview

This guide is the SDK equivalent of Rendering banners in Liquid. The browse payload, layout selection, and grid math are identical. With @commerce-blocks/sdk, sdk.collection() makes the HTTP call, deduplicates requests, caches the response, and exposes data.banners on reactive state you can subscribe to. Use this version when you have already installed @commerce-blocks/sdk in your theme. For a no-dependencies version, see the Liquid + Fetch guide. Hero banners are horizontal banners spanning the entire product grid above the first product row. They are not restricted to inline tile sizes. Inline banners can span one or more columns, bounded by the grid rather than a fixed 1×1 or 2×2 preset. Inline sizes are grid-cell spans, not image dimensions in pixels. The editor can resize inline banners across columns and up to four rows.

Prerequisites

The Layers Shopify app installed and the theme app extension enabled in Online Store → Themes → Customize → App embeds.
The SDK installed and initialized in your theme. See SDK installation.
At least one merchandising rule with banners attached. See Add a banner to a rule.

Banners ship as a top-level, pre-sorted array on the collection controller’s data:

data.banners
// → Array<{
//     id: string,
//     rule_id: string | null,       // ID of the merchandising rule that produced the banner
//     name: string,
//     mode: 'overtake' | 'inject',
//     link: string | null,
//     type: string,                 // 'link' for the built-in type, or your custom type's slug
//     data: Record<string, unknown>,// values for that type's field schema
//     sort_index: number,
//     web_media:    { id, src, alt, width, height, source, mediaContentType },
//     mobile_media: { id, src, alt, width, height, source, mediaContentType },
//     web_layout:   { placement: 'hero' | 'inline', width, height, position },
//     mobile_layout:{ placement: 'hero' | 'inline', width, height, position },
//   }>

Each banner carries the rule_id of the merchandising rule that produced it. data._meta.appliedRules (a flat array of rule ID strings) still lists every applied rule. Four parts of the banner payload matter for rendering:

Per-device media and layout. Pick web_* on desktop and mobile_* on mobile. They’re independent. A hero on web can be an inline tile on mobile.
Mode. overtake replaces the product card at position. inject inserts the banner and shifts trailing products by one cell.
Link. On the built-in link type, only inject banners can carry a top-level link. Wrap them in an anchor. Render overtake banners as plain media. Custom banner types put their click-through URL inside data instead.
Type and data. type is the banner type slug: 'link' for the built-in type, or the slug of one of your custom types. data carries the values of that type’s field schema. Switch renderers on type and read fields out of data.

sdk.collection() returns a reactive controller. Subscribe once and read data.products and data.banners from the same payload.

import { getSDK } from '@commerce-blocks/sdk'

const { data: sdk, error: sdkError } = getSDK()
if (sdkError) {
  console.error('SDK not initialized:', sdkError.message)
}

const collection = sdk.collection({ collectionHandle: COLLECTION_HANDLE })

collection.subscribe(({ data, loading, error }) => {
  if (loading || error || !data) return
  render({
    products: data.products ?? [],
    banners:  data.banners  ?? [],
  })
})

collection.get({ pagination: { page: 1, limit: 24 } })

The SDK dedupes identical requests and caches responses in memory for the life of the page. It re-runs the subscriber whenever you call get() with new filter or pagination args.

Step 2: Pick the layout for the current device

A banner only has a usable layout when both the media slot and the layout for the active device are present. Skip banners that don’t have both.

const mql = window.matchMedia('(max-width: 749px)')
const isMobile = () => mql.matches

function layoutForDevice(banner) {
  const media  = isMobile() ? banner.mobile_media  : banner.web_media
  const layout = isMobile() ? banner.mobile_layout : banner.web_layout
  if (!media?.src || !layout) return null
  return { media, layout, mode: banner.mode, link: banner.link, id: banner.id }
}

Listen for mql.addEventListener('change', ...) and re-render when the breakpoint flips. Banners can have completely different layouts per device. A 2×2 web tile may be a hero on mobile.

Step 3: Place banners around the products

Hero banners render across the full grid width above the products. Ignore their inline width and height cell spans; your theme controls the hero’s height and image cropping. Inline banners slot into the product grid by position (row-major, 0-indexed). overtake replaces the product at that index; inject splices the banner in and shifts trailing products. The response is already sorted by sort_index, so no extra sort is needed.

function render({ products, banners }) {
  const host = document.querySelector('.collection')
  const grid = document.querySelector('.collection__grid')

  // Clear previously rendered hero banners.
  host.querySelectorAll('.layers-banner--hero').forEach((el) => el.remove())

  // Hero banners - render above the grid.
  for (const banner of banners) {
    const picked = layoutForDevice(banner)
    if (picked?.layout.placement === 'hero') renderHero(host, picked)
  }

  // Inline banners - combined with products into grid cells.
  const cells = buildGridCells(products, banners)
  grid.innerHTML = cells.map(renderCell).join('')
}

function buildGridCells(products, banners) {
  const cells = products.map((p) => ({ type: 'product', product: p }))

  const inline = banners
    .map((b) => ({ banner: b, picked: layoutForDevice(b) }))
    .filter(({ picked }) => picked && picked.layout.placement === 'inline')

  for (const { picked } of inline) {
    const position = picked.layout.position ?? 0
    const cell = {
      type: 'banner',
      mode: picked.mode,
      link: picked.link,
      media: picked.media,
      width: picked.layout.width,
      height: picked.layout.height,
      id: picked.id,
    }

    if (picked.mode === 'overtake') {
      if (position < cells.length) cells[position] = cell
      else cells.push(cell)
    } else {
      cells.splice(Math.min(position, cells.length), 0, cell)
    }
  }

  return cells
}

function renderCell(cell) {
  if (cell.type === 'product') return renderProductCell(cell.product)

  const inner = `<img src="${cell.media.src}" alt="${cell.media.alt ?? ''}" />`
  const style = `--span-x:${cell.width};--span-y:${cell.height}`
  const classes = `layers-banner layers-banner--inline layers-banner--${cell.mode}`

  if (cell.mode === 'inject' && cell.link) {
    return `<a href="${cell.link}" class="${classes}" data-banner-id="${cell.id}" style="${style}">${inner}</a>`
  }
  return `<div class="${classes}" data-banner-id="${cell.id}" style="${style}">${inner}</div>`
}

function renderHero(host, picked) {
  const wrapper = picked.mode === 'inject' && picked.link
    ? `<a href="${picked.link}" class="layers-banner layers-banner--hero" data-banner-id="${picked.id}">`
    : `<div class="layers-banner layers-banner--hero" data-banner-id="${picked.id}">`
  const closing = picked.mode === 'inject' && picked.link ? '</a>' : '</div>'

  host.insertAdjacentHTML(
    'afterbegin',
    `${wrapper}<img src="${picked.media.src}" alt="${picked.media.alt ?? ''}" />${closing}`,
  )
}

Use grid-column: span <width>; grid-row: span <height> (or the --span-x / --span-y properties) on banner cells so 2×2 tiles actually cover four grid cells.

function renderProductCell(product) {
  return `
    <a href="/products/${product.handle}" class="product-card">
      <img src="${product.featuredMedia?.url ?? ''}" alt="" />
      <h3>${product.title}</h3>
      <span>${product.price?.formatted ?? ''}</span>
    </a>
  `
}

Re-running on filter or pagination changes

Reuse the same collection controller and subscriber, and call get() with new args. Layers recomputes the banner payload on every request, so banners are always in sync with the current filter set.

collection.get({
  filterGroup: activeFilters,
  pagination: { page, limit: 24 },
})

The rendering steps on this page work unchanged for the built-in Link type. If you’ve defined custom banner types, each banner also carries a type slug and a data object with the type’s saved field values. Switch renderers on type and read fields out of data. The envelope (media, layout, mode) is the same across all types.

type PickedBanner = ReturnType<typeof layoutForDevice>

function layoutForDevice(banner) {
  const media  = isMobile() ? banner.mobile_media  : banner.web_media
  const layout = isMobile() ? banner.mobile_layout : banner.web_layout
  if (!media?.src || !layout) return null
  return {
    media,
    layout,
    mode: banner.mode,
    link: banner.link,
    type: banner.type,
    data: banner.data ?? {},
    id: banner.id,
  }
}

function renderBannerBody(picked: NonNullable<PickedBanner>) {
  const { type, data } = picked
  switch (type) {
    case 'link':
      return `<img src="${picked.media.src}" alt="${picked.media.alt ?? ''}" />`

    case 'countdown_promo':
      return `
        <img src="${picked.media.src}" alt="${picked.media.alt ?? ''}" />
        <h3>${escapeHtml(String(data.headline ?? ''))}</h3>
        <time datetime="${data.end_at}">${escapeHtml(String(data.cta_label ?? 'Shop the drop'))}</time>
      `

    case 'spotlight_product':
      // product_reference fields arrive pre-resolved to { id, handle }.
      return `
        <a href="/products/${data.spotlight_product?.handle ?? ''}">
          <img src="${picked.media.src}" alt="${picked.media.alt ?? ''}" />
          <span>${escapeHtml(String(data.overlay_label ?? ''))}</span>
        </a>
      `

    default:
      // Unknown type - fall back to the media so a newly-added type still renders.
      return `<img src="${picked.media.src}" alt="${picked.media.alt ?? ''}" />`
  }
}

Reference fields (product_reference, collection_reference, variant_reference) arrive pre-resolved to { id, handle }. Unpublished references are dropped from the payload, so you don’t need to guard against dead handles. Retyped or removed fields on the banner type are dropped too. Treat any field on data as optional and fall back cleanly.

Fallback rules

Per Banner Injection:

A banner without both the device’s media slot and layout is treated as disabled. layoutForDevice returns null and you skip it.
A banner without web_media or mobile_media filled is never enabled by Layers, so it won’t appear in the payload in the first place.
Banners with mode: 'overtake' ignore any link value. Only inject banners are clickable.

What the app embed handles for you

The Layers theme app extension does not render banners. Your theme owns that. The embed does handle:

Authenticating the browse request (token, cart context, identity).
Sending the storefront pixel events that track shopper engagement on the underlying grid.

The storefront pixel also tracks banner_impression and banner_click events automatically for any rendered element whose data-banner-id matches a banner id from the Layers response, as in the examples above. Keep that attribute on your banner markup so these events fire.

Why the SDK over Fetch

Concern	Fetch version	SDK version
Driving the request	`fetch` to `/browse/{handle}`	`collection.get()`
Re-renders	DIY DOM updates	`subscribe()` callback
Caching during the page	DIY	In-memory cache and request deduplication
Re-rendering on filter change	Manual orchestration	Same controller, call `get()` again
Banner placement	Same: your theme owns the grid math	Same: your theme owns the grid math

Troubleshooting

data.banners is empty. No merchandising rule matched the request, or every matching rule had no enabled banners. Confirm at least one active rule on this collection has banners attached and both media slots filled. Banners only appear on first load, not after filtering. Your subscriber probably re-renders products but not banners. Re-read data.banners from the same payload on every state update. They ship together. Inline banner is at the wrong cell. position is row-major and 0-indexed. Verify the device’s *_layout.position matches the cell index you expect after flattening the grid to a single array. 2×2 inline tile renders as a 1×1. Your CSS isn’t honoring width/height. Apply grid-column: span <width>; grid-row: span <height> on banner cells.

Liquid Integration

Liquid + Fetch guides

Liquid + SDK guides

Rendering banners with the SDK

Overview

Prerequisites

The banner payload

Step 2: Pick the layout for the current device

Step 3: Place banners around the products

Custom banner types

Fallback rules

What the app embed handles for you

Why the SDK over Fetch

Troubleshooting

See also

​Overview

​Prerequisites

​The banner payload

​Step 1: Subscribe to the collection controller

​Step 2: Pick the layout for the current device

​Step 3: Place banners around the products

​Re-running on filter or pagination changes

​Custom banner types

​Fallback rules

​What the app embed handles for you

​Why the SDK over Fetch

​Troubleshooting

​See also

Overview

Prerequisites

The banner payload

Step 1: Subscribe to the collection controller

Step 2: Pick the layout for the current device

Step 3: Place banners around the products

Re-running on filter or pagination changes

Custom banner types

Fallback rules

What the app embed handles for you

Why the SDK over Fetch

Troubleshooting

See also