---
title: Migrate ImageGroup to the Polaris image group component
description: >-
  Learn how to migrate the ImageGroup component to Polaris web components in
  customer account UI extensions.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components/image-group
  md: >-
    https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components/image-group.md
---

# 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`](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/components/media-and-visuals/imagegroup) component and is available as [`<s-image-group>`](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/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>`](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/section) and as a stacked layout everywhere else.

## Migrating ImageGroup to s-image-group

##### Latest (Preact)

```jsx
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>
  );
}
```

##### Pre-Polaris (2025-07)

```jsx
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>
  );
}
```

***

## Removed properties

### variant

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>`](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/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.

## Migrating variant=grid to s-section

##### Latest (Preact)

```jsx
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>
  );
}
```

##### Pre-Polaris (2025-07)

```jsx
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>
  );
}
```

### accessibility​Label

The previous `ImageGroup` `accessibilityLabel` prop has been removed. Describe each image with its own `alt` text on the child [`<s-image>`](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/image) elements instead.

### loading

The previous `ImageGroup` `loading` prop has been removed.

***

## Further guidance

### Recreating 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>`](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/grid) that uses overlapping column widths.

## Recreating inline-stack with s-grid

##### Latest (Preact)

```jsx
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>
  );
}
```

##### Pre-Polaris (2025-07)

```jsx
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>
  );
}
```

***