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

# Migrate to the Polaris image component

The Polaris image component renders images with built-in responsive behavior and accessibility support. It replaces the previous [`Image`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/media/image) component and is available as [`<s-image>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris image component.

### source

The previous `Image` `source` prop is now called [`src`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-src).

## Migrating source to src

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-image
      src="https://example.com/product.jpg"
      alt="Product image"
    />
  );
}
```

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

```tsx
import {
  reactExtension,
  Image,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Image
      source="https://example.com/product.jpg"
      accessibilityDescription="Product image"
    />
  );
}
```

### accessibility​Description

The previous `Image` `accessibilityDescription` prop is now called [`alt`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-alt).

### corner​Radius

The previous `Image` `cornerRadius` prop is now called [`borderRadius`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-borderradius). Most token values carry over (`none`, `small`, `base`, `large`), but a few things changed:

| Previous value | New value | Migration notes |
| - | - | - |
| `'fullyRounded'` | `'max'` | Renamed. |
| Not available | `'small-100'`, `'large-100'` | New intermediate scale tokens. |

### fit

The previous `Image` `fit` prop is now called [`objectFit`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-objectfit).

### accessibility​Role

The [`accessibilityRole`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-accessibilityrole) value for decorative images has changed to align with the standard ARIA role. The intent is the same — the image carries no semantic meaning and assistive technologies should ignore it — but the value uses the web-standard name.

| Previous value | New value | Migration notes |
| - | - | - |
| `'decorative'` | `'presentation'` (or `'none'`) | Same intent as `'decorative'`: the image is purely decorative and is skipped by assistive technologies. `'presentation'` and `'none'` are equivalent ARIA roles. |

## Migrating accessibilityRole

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-image
      src="https://example.com/decoration.jpg"
      alt=""
      accessibilityRole="presentation"
    />
  );
}
```

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

```tsx
import {
  reactExtension,
  Image,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Image
      source="https://example.com/decoration.jpg"
      accessibilityDescription=""
      accessibilityRole="decorative"
    />
  );
}
```

### aspect​Ratio

The [`aspectRatio`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-aspectratio) prop now accepts string values instead of numbers. The string can be a single number (for example, `"1.5"`) or a CSS-style ratio (for example, `"16/9"`) — you don't need to pre-calculate the decimal. The default is `"1/1"`.

| Previous value | New value | Migration notes |
| - | - | - |
| `{1.5}` (number) | `"1.5"` (string) | Wrap number values in quotes. |
| `{16/9}` (expression) | `"16/9"` (string) | Keep the ratio as-is — `<s-image>` accepts the `a/b` syntax. |

## Migrating aspectRatio

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-image
      src="https://example.com/product.jpg"
      alt="Product image"
      aspectRatio="1.5"
    />
  );
}
```

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

```tsx
import {
  reactExtension,
  Image,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Image
      source="https://example.com/product.jpg"
      accessibilityDescription="Product image"
      aspectRatio={1.5}
    />
  );
}
```

### source with responsive conditions

The previous pattern of passing an object with `resolution` or `viewportInlineSize` conditions to `source` is now handled with standard [`srcSet`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-srcset) and [`sizes`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-sizes) attributes.

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `source="url"` | `src="url"` | Simple source renamed to `src`. |
| `source={{default: 'url', resolution: {'2x': 'url@2x'}}}` | `src="url"` + `srcSet="url 1x, url@2x 2x"` | Resolution conditions use `srcSet`. |
| `source={{default: 'url', viewportInlineSize: {small: 'small.jpg'}}}` | `src="url"` + `srcSet="small.jpg 400w"` + `sizes="..."` | Viewport-based sources use `srcSet` with `sizes`. |

`srcSet` accepts both width descriptors (for example, `400w`) and pixel-density descriptors (for example, `2x`). Width descriptors with a matching `sizes` attribute are the more common choice for viewport-responsive images.

## Migrating responsive source to srcSet with width descriptors

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-image
      src="https://example.com/product-800.jpg"
      srcSet="https://example.com/product-400.jpg 400w, https://example.com/product-800.jpg 800w, https://example.com/product-1200.jpg 1200w"
      sizes="(min-width: 900px) 1200px, 100vw"
      alt="Product image"
    />
  );
}
```

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

```tsx
import {
  reactExtension,
  Image,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Image
      source={{
        default: 'https://example.com/product-800.jpg',
        viewportInlineSize: {
          small: 'https://example.com/product-400.jpg',
          large: 'https://example.com/product-1200.jpg',
        },
      }}
      accessibilityDescription="Product image"
    />
  );
}
```

For pixel-density-only responsiveness, use the `1x`/`2x` form instead: `srcSet="product.jpg 1x, product@2x.jpg 2x"` (no `sizes` attribute needed).

**Responsive values:**

If you used `Style.default().when()` to make this property responsive, container queries replace the `Style` helper. Wrap your content in `<s-query-container>` and use `@container` syntax in the property value. Learn more in [Migrate StyleHelper to container queries](https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/style-helper).

***

## New properties

The Polaris image component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`srcSet`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-srcset) | `string` | Defines multiple image sources for different resolutions or viewport sizes. |
| [`sizes`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-sizes) | `string` | Defines the image sizes for different viewport conditions (used with `srcSet`). |
| [`inlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-inlinesize) | `'auto'` \| `'fill'` | Controls the width behavior of the image. Default is `'fill'`. |
| [`borderStyle`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image#properties-propertydetail-borderstyle) | `'auto'` \| `'none'` \| `'solid'` \| `'dashed'` \| `'dotted'` | Sets the border style independently of the `border` shorthand. Accepts a single keyword or a CSS-like shorthand of up to four values. |

***