---
title: Migrate Image from Polaris React
description: Learn how to migrate Polaris React Image to Polaris web components.
source_url:
html: >-
https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/image
md: >-
https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/image.md
api_name: app-home
---
# Migrate Image from Polaris React
Use `s-image` for content imagery and preserve meaningful alternative text. Use empty alternative text for decorative images rather than repeating nearby content.
***
## Choose the destination
| Polaris React | Polaris web components | Migration type |
| - | - | - |
| `Image` | [`s-image`](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/image) | Direct |
***
## Map image properties
| Polaris React | Polaris web components | Migration notes |
| - | - | - |
| `source` and `alt` | `src` and `alt` | Preserve the trusted image URL and correct alternative text. |
| `sourceSet` | `srcSet` | Provide the available image candidates and their width or density descriptors. |
| Responsive display width | `sizes` with `inlineSize="fill"` or `"auto"` | `sizes` tells the browser how wide the image will render so it can choose a `srcSet` candidate; `inlineSize` controls whether the component fills its container or uses its natural size. |
| Reserved shape and cropping | `aspectRatio` and `objectFit` | Reserve the final shape before loading. Use `contain` to show the complete image or `cover` when intentional cropping is acceptable. |
| `fit` and load callbacks | `objectFit`, `onLoad`, and `onError` | Recheck cropping and reconnect fallbacks to DOM events. |
`srcSet` doesn't size the rendered component by itself. Pair it with an accurate `sizes` value and a containing layout whose inline size is known. Set `aspectRatio` when the layout should reserve space before the selected source loads.
***
## Migrate the call site
1. Inventory every `Image` call site and record the content, state, events, and accessibility behavior it uses.
2. Open the linked Polaris web component reference and map only documented properties, slots, and events.
3. Move unsupported responsibilities into adjacent content or app state instead of passing old props through.
4. After verification, remove the `Image` import and any Polaris-only state, wrappers, or helpers that no longer have a caller.
***
## Preserve these behaviors
* Accessible names, semantics, and keyboard behavior.
* Visible content plus disabled, loading, selected, or error state that affects the task.
* Click, change, submit, and navigation behavior used by app logic.
***
## Test and remove Polaris React
Test every migrated `Image` state used by the app. For interactive destinations, verify keyboard operation, focus, and accessible naming. For content destinations, verify document structure and alternative text where applicable. Compare behavior rather than pixel-for-pixel styling.
Don't remove `@shopify/polaris` while another component still imports it. Once all call sites are migrated, remove the package and its provider-level setup, then run the app's full test suite.
***
## Migration example
## Migrating Image
##### Polaris web components
```tsx
export function ImageMigrationExample() {
return (
<>
);
}
```
##### Polaris React
```tsx
import {Image} from '@shopify/polaris';
export function ImageMigrationExample() {
return (
);
}
```
***