Migrate ImageGroup to the Polaris image group component

The Polaris image group component displays up to four images together with an optional count of additional items. It replaces the previous ImageGroup component and is available as <s-image-group> in API versions 2025-10 and newer.

The biggest change is that layout is now context-driven. The previous ImageGroup used a variant prop to switch between grid and inline-stack. <s-image-group> renders as a grid inside a <s-section> and as a stacked layout everywhere else.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-image-group totalItems={6}>
      <s-image src="https://example.com/plant-1.jpg" alt="Golden pothos" />
      <s-image src="https://example.com/plant-2.jpg" alt="Watering can" />
      <s-image src="https://example.com/plant-3.jpg" alt="Fiddle leaf fig" />
      <s-image src="https://example.com/plant-4.jpg" alt="Fern" />
    </s-image-group>
  );
}

import {
  Image,
  ImageGroup,
  reactExtension,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <ImageGroup totalItems={6}>
      <Image source="https://example.com/plant-1.jpg" accessibilityDescription="Golden pothos" />
      <Image source="https://example.com/plant-2.jpg" accessibilityDescription="Watering can" />
      <Image source="https://example.com/plant-3.jpg" accessibilityDescription="Fiddle leaf fig" />
      <Image source="https://example.com/plant-4.jpg" accessibilityDescription="Fern" />
    </ImageGroup>
  );
}

Anchor to Removed propertiesRemoved properties

Anchor to variantvariant

The previous ImageGroup variant prop has been removed. Layout is now determined by the parent: <s-image-group> renders as a grid inside a <s-section> and as a stacked layout in other contexts.

To get the previous variant="grid" layout, wrap <s-image-group> in an <s-section>. This also applies the section's styles based on the merchant's branding settings.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-section>
      <s-image-group totalItems={6}>
        <s-image src="https://example.com/plant-1.jpg" alt="Golden pothos" />
        <s-image src="https://example.com/plant-2.jpg" alt="Watering can" />
        <s-image src="https://example.com/plant-3.jpg" alt="Fiddle leaf fig" />
        <s-image src="https://example.com/plant-4.jpg" alt="Fern" />
      </s-image-group>
    </s-section>
  );
}

import {
  Image,
  ImageGroup,
  reactExtension,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <ImageGroup variant="grid" totalItems={6}>
      <Image source="https://example.com/plant-1.jpg" accessibilityDescription="Golden pothos" />
      <Image source="https://example.com/plant-2.jpg" accessibilityDescription="Watering can" />
      <Image source="https://example.com/plant-3.jpg" accessibilityDescription="Fiddle leaf fig" />
      <Image source="https://example.com/plant-4.jpg" accessibilityDescription="Fern" />
    </ImageGroup>
  );
}

Anchor to accessibilityLabelaccessibilityLabel

The previous ImageGroup accessibilityLabel prop has been removed. Describe each image with its own alt text on the child <s-image> elements instead.

Anchor to loadingloading

The previous ImageGroup loading prop has been removed.

Anchor to Further guidanceFurther guidance

Anchor to Recreating the inline-stack image group layoutRecreating the inline-stack image group layout

The previous ImageGroup variant="inline-stack" rendered images as a compact overlapping horizontal stack, regardless of context. <s-image-group> renders as a stacked layout outside <s-section> automatically, so you only need this recreation pattern when you want the overlapping look inside an <s-section>, where <s-image-group> renders as a grid. Compose it yourself with an <s-grid> that uses overlapping column widths.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-section heading="Wishlist">
      <s-grid gridTemplateColumns="28px 28px 28px 42px" alignItems="center">
        <s-box
          inlineSize="42px"
          blockSize="42px"
          border="base"
          borderRadius="base"
          overflow="hidden"
        >
          <s-image
            src="https://example.com/product-1.jpg"
            alt="Blue t-shirt"
            aspectRatio="1/1"
            objectFit="cover"
          />
        </s-box>
        <s-box
          inlineSize="42px"
          blockSize="42px"
          border="base"
          borderRadius="base"
          overflow="hidden"
        >
          <s-image
            src="https://example.com/product-2.jpg"
            alt="Red mug"
            aspectRatio="1/1"
            objectFit="cover"
          />
        </s-box>
        <s-box
          inlineSize="42px"
          blockSize="42px"
          border="base"
          borderRadius="base"
          overflow="hidden"
        >
          <s-image
            src="https://example.com/product-3.jpg"
            alt="Canvas tote"
            aspectRatio="1/1"
            objectFit="cover"
          />
        </s-box>
        <s-stack
          direction="inline"
          inlineSize="42px"
          blockSize="42px"
          borderRadius="large-100"
          border="large base solid"
          background="subdued"
          alignItems="center"
          justifyContent="center"
        >
          <s-text>+3</s-text>
        </s-stack>
      </s-grid>
    </s-section>
  );
}

import {
  Image,
  ImageGroup,
  reactExtension,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <ImageGroup variant="inline-stack" totalItems={6}>
      <Image source="https://example.com/product-1.jpg" accessibilityDescription="Blue t-shirt" />
      <Image source="https://example.com/product-2.jpg" accessibilityDescription="Red mug" />
      <Image source="https://example.com/product-3.jpg" accessibilityDescription="Canvas tote" />
    </ImageGroup>
  );
}