---
title: ImageGroup
description: >-
Display up to 4 images in a grid or stacked layout. For example, images of
products in a wishlist or subscription.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/imagegroup
md: >-
https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/imagegroup.md
---
Migrate to Polaris
Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.
# ImageGroup
The ImageGroup component displays up to four images in a grid or stacked layout. Use ImageGroup to showcase collections of related images, such as products in a wishlist or subscription.
When there are more than four images, the component indicates how many additional images aren't displayed, giving customers a clear sense of the full collection size. The `variant` property controls whether images display in a `grid` or `inline-stack` layout.
### Support Targets (25)
### Supported targets
* CustomerAccount::KitchenSink
* [customer-account.footer.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.order-index.announcement.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.order-index.block.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.order-status.announcement.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.order-status.block.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.order-status.cart-line-item.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.order-status.cart-line-list.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.order-status.customer-information.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.order-status.fulfillment-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.order-status.payment-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.order-status.return-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.order-status.unfulfilled-items.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.order.action.menu-item.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.order.action.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.order.page.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.page.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.profile.addresses.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.profile.announcement.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.profile.block.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.profile.company-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.profile.company-location-addresses.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.profile.company-location-payment.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.profile.company-location-staff.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.profile.payment.render-after
#### Use cases
* **Order summaries**: Display product images from a recent order in a compact visual group.
* **Wishlists and collections**: Show a preview of saved items with a count of additional products.
* **Subscription overviews**: Present the products included in a recurring subscription.
* **Visual previews**: Provide a quick visual snapshot of related items without taking up significant space.
***
## Properties
Configure the following properties on the ImageGroup component.
* **accessibilityLabel**
**string**
A label that describes the purpose or contents of the image group. When set, it will be announced to users using assistive technologies and will provide them with more context.
* **loading**
**boolean**
**Default: false**
The loading state of the image group. When `true`, the image group displays a loading indicator in place of images.
* **totalItems**
**number**
The total number of items that could be displayed in the image group. Used to calculate and display the remaining count when all available image slots have been filled (for example, "+3 more").
* **variant**
**'grid' | 'inline-stack'**
**Default: 'grid'**
The layout arrangement for the images within the group.
* `grid`: Displays images in a grid layout, filling available rows and columns.
* `inline-stack`: Displays images in a horizontal stack, arranged inline from start to end.
***
## Examples
### Display an image group
Show a collection of related images in a compact layout. This example displays three product images in the default grid arrangement.
## Display an image group
## Display an image group
##### React
```tsx
import {
Image,
ImageGroup,
View,
reactExtension,
} from '@shopify/ui-extensions-react/customer-account';
import React from 'react';
export default reactExtension('customer-account.page.render', () => );
function App() {
return (
);
}
```
##### JS
```js
import {
Image,
ImageGroup,
View,
extension,
} from '@shopify/ui-extensions/customer-account';
export default extension(
'customer-account.page.render',
(root, api) => {
renderApp(root, api);
},
)
function renderApp(root, api) {
const firstImage = root.createComponent(Image, {
source: "../assets/flower.jpg"
});
const secondeImage = root.createComponent(Image, {
source: "../assets/flower.jpg"
});
const thirdImage = root.createComponent(Image, {
source: "../assets/flower.jpg"
});
const imageGroup = root.createComponent(ImageGroup);
imageGroup.append(firstImage);
imageGroup.append(secondeImage);
imageGroup.append(thirdImage);
const view = root.createComponent(View, {maxInlineSize: 300});
view.append(imageGroup);
root.append(view);
}
```
### Display subscription items
Show subscription items with delivery details. This example places an image group inside a [Section](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/card) alongside the next delivery date and pricing information.
## Display subscription items
##### React
```tsx
import {
reactExtension,
Image,
ImageGroup,
Text,
Heading,
BlockStack,
Section,
View,
} from '@shopify/ui-extensions-react/customer-account';
export default reactExtension(
'customer-account.page.render',
() => ,
);
function Extension() {
return (
Monthly subscription
Next delivery: April 15, 2026
2 items · $45.00/month
);
}
```
##### JS
```js
import {extension, Image, ImageGroup, Text, Heading, BlockStack, Section, View} from '@shopify/ui-extensions/customer-account';
export default extension('customer-account.page.render', (root) => {
const img1 = root.createComponent(Image, {
source: 'https://cdn.shopify.com/static/sample-product/House-Plant1.png',
accessibilityLabel: 'Indoor plant in a gray pot',
});
const img2 = root.createComponent(Image, {
source: 'https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg',
accessibilityLabel: 'White sneakers',
});
const group = root.createComponent(ImageGroup);
group.append(img1);
group.append(img2);
const delivery = root.createComponent(Text, {}, 'Next delivery: April 15, 2026');
const price = root.createComponent(Text, {appearance: 'subdued'}, '2 items · $45.00/month');
const heading = root.createComponent(Heading, {}, 'Monthly subscription');
const stack = root.createComponent(BlockStack, {spacing: 'base'});
stack.append(group);
stack.append(delivery);
stack.append(price);
const section = root.createComponent(Section);
section.append(heading);
section.append(stack);
const view = root.createComponent(View, {maxInlineSize: 300});
view.append(section);
root.append(view);
});
```
***
## Best practices
* **Write concise alt text for each image**: Describe what's important about each image so all customers can understand the content, even when using assistive technologies.
* **Optimize performance**: Compress images and use modern formats like WebP. Consider lazy loading to reduce initial load times, especially when displaying multiple groups on a page.
* **Use consistent image dimensions**: Provide images with similar aspect ratios to maintain a clean, uniform grid appearance.
* **Preserve visual breathing room**: Maintain consistent spacing around the group so images don't feel crowded or overwhelming within the layout.
***
## Limitations
* The component displays a maximum of four images at a time. Additional images are represented by a count indicator rather than being displayed.
* All images in the group share the same display size. Individual image sizing or aspect ratio overrides aren't supported within the group.
* Use `totalItems` to display a count indicator when the total exceeds the number of images shown.
***