Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Image

The Image component displays an image from a URL. It supports accessibility labels (or alt text), lazy loading, load and error callbacks, and a decorative mode for images that should be ignored by screen readers.

For rendering Polaris icons, use Icon.

Support

Targets (46)

Supported targets

Anchor to PropertiesProperties

Props for the Image component. Requires either accessibilityLabel or alt for alternative text, and either source or src for the image URL.

(ImageAccessibilityLabelProp | ImageAltProp) & (ImageSourceProp | ImageSrcProp) & ImageBaseProps

Anchor to ImageAccessibilityLabelProp

ImageAccessibilityLabelProp

Anchor to accessibilityLabel accessibilityLabel string required: Alternative text that describes the image for assistive technologies. Screen readers announce this text when they encounter the image, and it displays as a fallback if the image fails to load. An alt prop is available as an alias.

Learn more about writing effective alternative text.
Anchor to alt alt never: The alternative text for the image. Typed as never on this variant because accessibilityLabel is already set. To use alt instead, omit accessibilityLabel.

Anchor to ImageAltProp

ImageAltProp

Anchor to alt alt string required: An alias for accessibilityLabel. Alternative text that describes the image for assistive technologies. Screen readers announce this text when they encounter the image, and it displays as a fallback if the image fails to load.

Learn more about writing effective alternative text.
Anchor to accessibilityLabel accessibilityLabel never: The alternative text for the image. Typed as never on this variant because alt is already set. To use accessibilityLabel instead, omit alt.

Anchor to ImageBaseProps

ImageBaseProps

Anchor to accessibilityRole accessibilityRole: The semantic role of the image for assistive technologies.

decorative: Marks the image as purely visual, so screen readers skip it entirely. Use this for images that don't convey meaningful content (like background patterns or visual flourishes).
Anchor to id id string: A unique identifier for the image. Must be unique within the entire extension.
Anchor to loading loading 'eager' | 'lazy' Default: 'eager': Controls when the image starts loading.

eager: Loads the image immediately, regardless of whether it's visible in the viewport.

lazy: Defers loading until the image approaches the viewport, which can improve initial page performance.
Anchor to onError onError () => void: A callback that fires when the image fails to load (for example, due to a broken URL or network error). Use this to show a fallback or error state.
Anchor to onLoad onLoad () => void: A callback that fires when the image finishes loading successfully. Use this to trigger UI updates that depend on the image being ready (for example, removing a loading skeleton).

Anchor to ImageSourceProp

ImageSourceProp

Anchor to source source string required: The URL of the image to display. Supports remote URLs and local file resources. Blob URLs aren't currently supported. A src prop is available as an alias.
Anchor to src src never: The URL of the image to display. Typed as never on this variant because source is already set. To use src instead, omit source.

Anchor to ImageSrcProp

ImageSrcProp

Anchor to src src string required: An alias for source. The URL of the image to display. Supports remote URLs and local file resources. Blob URLs aren't currently supported.
Anchor to source source never: The URL of the image to display. Typed as never on this variant because src is already set. To use source instead, omit src.

ImageAccessibilityLabelProp

Variant that uses `accessibilityLabel` for alternative text.

accessibilityLabel
Alternative text that describes the image for assistive technologies. Screen readers announce this text when they encounter the image, and it displays as a fallback if the image fails to load. An `alt` prop is available as an alias. Learn more about [writing effective alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204).
```
string
```
alt
The alternative text for the image. Typed as `never` on this variant because `accessibilityLabel` is already set. To use `alt` instead, omit `accessibilityLabel`.
```
never
```

ImageAltProp

Variant that uses `alt` for alternative text.

accessibilityLabel
The alternative text for the image. Typed as `never` on this variant because `alt` is already set. To use `accessibilityLabel` instead, omit `alt`.
```
never
```
alt
An alias for `accessibilityLabel`. Alternative text that describes the image for assistive technologies. Screen readers announce this text when they encounter the image, and it displays as a fallback if the image fails to load. Learn more about [writing effective alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204).
```
string
```

ImageSourceProp

Variant that uses `source` for the image URL.

source
The URL of the image to display. Supports remote URLs and local file resources. Blob URLs aren't currently supported. A `src` prop is available as an alias.
```
string
```
src
The URL of the image to display. Typed as `never` on this variant because `source` is already set. To use `src` instead, omit `source`.
```
never
```

ImageSrcProp

Variant that uses `src` for the image URL.

source
The URL of the image to display. Typed as `never` on this variant because `src` is already set. To use `source` instead, omit `src`.
```
never
```
src
An alias for `source`. The URL of the image to display. Supports remote URLs and local file resources. Blob URLs aren't currently supported.
```
string
```

ImageBaseProps

Base props shared by all Image variants.

accessibilityRole
The semantic role of the image for assistive technologies. - `decorative`: Marks the image as purely visual, so screen readers skip it entirely. Use this for images that don't convey meaningful content (like background patterns or visual flourishes).
id
A unique identifier for the image. Must be unique within the entire extension.
```
string
```
loading
Controls when the image starts loading. - `eager`: Loads the image immediately, regardless of whether it's visible in the viewport. - `lazy`: Defers loading until the image approaches the viewport, which can improve initial page performance.
```
'eager' | 'lazy'
```
onError
A callback that fires when the image fails to load (for example, due to a broken URL or network error). Use this to show a fallback or error state.
```
() => void
```
onLoad
A callback that fires when the image finishes loading successfully. Use this to trigger UI updates that depend on the image being ready (for example, removing a loading skeleton).
```
() => void
```

Anchor to ExamplesExamples

Anchor to Display product featured imageDisplay product featured image

Fetch a product's featured image from the GraphQL Admin API and show it with alt text. This example queries the product.featuredImage field and displays the result in an Image component with an accessibilityLabel that falls back to the product title.

Display product featured image

Fetch a product's featured image from the [GraphQL Admin API](/docs/api/admin-graphql/) and show it with alt text. This example queries the `product.featuredImage` field and displays the result in an `Image` component with an `accessibilityLabel` that falls back to the product title.

Display product featured image

import {useState, useEffect} from 'react';

import {reactExtension, useApi, Image, Text, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {

const {data, query} = useApi('admin.product-details.block.render');

const productId = data.selected[0]?.id;

const [product, setProduct] = useState(null);

useEffect(() => {

query(

`query Product($id: ID!) {

product(id: $id) {

title

featuredImage { url altText }

}

}`,

{variables: {id: productId}},

).then((result) => setProduct(result?.data?.product));

}, [productId, query]);

if (!product?.featuredImage) return null;

return (

<Image

source={product.featuredImage.url}

accessibilityLabel={product.featuredImage.altText || product.title}

<Text>{product.title}</Text>

</BlockStack>

);

}

export default reactExtension(

'admin.product-details.block.render',

() => <App />,

);

import {extension, Image, Text, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(

'admin.product-details.block.render',

async (root, api) => {

const {data, query} = api;

const productId = data.selected[0]?.id;

const stack = root.createComponent(BlockStack);

const result = await query(

`query Product($id: ID!) {

product(id: $id) {

title

featuredImage { url altText }

}

}`,

{variables: {id: productId}},

);

const product = result?.data?.product;

if (product?.featuredImage) {

const image = root.createComponent(Image, {

source: product.featuredImage.url,

accessibilityLabel: product.featuredImage.altText || product.title,

});

const caption = root.createComponent(

Text,

{},

product.title,

);

stack.appendChild(image);

stack.appendChild(caption);

}

root.appendChild(stack);

);

React

import {useState, useEffect} from 'react';
import {reactExtension, useApi, Image, Text, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {
  const {data, query} = useApi('admin.product-details.block.render');
  const productId = data.selected[0]?.id;
  const [product, setProduct] = useState(null);

  useEffect(() => {
    query(
      `query Product($id: ID!) {
        product(id: $id) {
          title
          featuredImage { url altText }
        }
      }`,
      {variables: {id: productId}},
    ).then((result) => setProduct(result?.data?.product));
  }, [productId, query]);

  if (!product?.featuredImage) return null;

  return (
    <BlockStack>
      <Image
        source={product.featuredImage.url}
        accessibilityLabel={product.featuredImage.altText || product.title}
      />
      <Text>{product.title}</Text>
    </BlockStack>
  );
}

export default reactExtension(
  'admin.product-details.block.render',
  () => <App />,
);

TS

import {extension, Image, Text, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.block.render',
  async (root, api) => {
    const {data, query} = api;
    const productId = data.selected[0]?.id;

    const stack = root.createComponent(BlockStack);

    const result = await query(
      `query Product($id: ID!) {
        product(id: $id) {
          title
          featuredImage { url altText }
        }
      }`,
      {variables: {id: productId}},
    );

    const product = result?.data?.product;

    if (product?.featuredImage) {
      const image = root.createComponent(Image, {
        source: product.featuredImage.url,
        accessibilityLabel: product.featuredImage.altText || product.title,
      });

      const caption = root.createComponent(
        Text,
        {},
        product.title,
      );

      stack.appendChild(image);
      stack.appendChild(caption);
    }

    root.appendChild(stack);
  },
);

Anchor to Handle image loading statesHandle image loading states

Handle image loading and error states using onLoad and onError callbacks. This example shows a ProgressIndicator while the image loads and displays an error message if the image fails to load, preventing broken image placeholders.

Handle image loading states

import {useState} from 'react';

import {reactExtension, Image, Text, ProgressIndicator, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {

const [loading, setLoading] = useState(true);

const [error, setError] = useState(false);

return (

{loading && (

)}

{error ? (

<Text>Unable to load product image.</Text>

) : (

<Image

source="https://cdn.shopify.com/s/files/placeholder-images/product.png"

accessibilityLabel="Product preview"

loading="lazy"

onLoad={() => setLoading(false)}

onError={() => {

setLoading(false);

setError(true);

}}

)}

</BlockStack>

);

}

export default reactExtension(

'admin.product-details.block.render',

() => <App />,

);

import {extension, Image, Text, ProgressIndicator, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(

'admin.product-details.block.render',

(root) => {

const stack = root.createComponent(BlockStack);

const loader = root.createComponent(ProgressIndicator, {

size: 'small-100',

accessibilityLabel: 'Loading image',

});

stack.appendChild(loader);

const image = root.createComponent(Image, {

source: 'https://cdn.shopify.com/s/files/placeholder-images/product.png',

accessibilityLabel: 'Product preview',

loading: 'lazy',

onLoad: () => {

stack.removeChild(loader);

onError: () => {

stack.removeChild(loader);

const error = root.createComponent(

Text,

{},

'Unable to load product image.',

);

stack.appendChild(error);

});

stack.appendChild(image);

root.appendChild(stack);

);

React

import {useState} from 'react';
import {reactExtension, Image, Text, ProgressIndicator, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(false);

  return (
    <BlockStack>
      {loading && (
        <ProgressIndicator size="small-100" accessibilityLabel="Loading image" />
      )}
      {error ? (
        <Text>Unable to load product image.</Text>
      ) : (
        <Image
          source="https://cdn.shopify.com/s/files/placeholder-images/product.png"
          accessibilityLabel="Product preview"
          loading="lazy"
          onLoad={() => setLoading(false)}
          onError={() => {
            setLoading(false);
            setError(true);
          }}
        />
      )}
    </BlockStack>
  );
}

export default reactExtension(
  'admin.product-details.block.render',
  () => <App />,
);

TS

import {extension, Image, Text, ProgressIndicator, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.block.render',
  (root) => {

    const stack = root.createComponent(BlockStack);

    const loader = root.createComponent(ProgressIndicator, {
      size: 'small-100',
      accessibilityLabel: 'Loading image',
    });
    stack.appendChild(loader);

    const image = root.createComponent(Image, {
      source: 'https://cdn.shopify.com/s/files/placeholder-images/product.png',
      accessibilityLabel: 'Product preview',
      loading: 'lazy',
      onLoad: () => {
        stack.removeChild(loader);
      },
      onError: () => {
        stack.removeChild(loader);
        const error = root.createComponent(
          Text,
          {},
          'Unable to load product image.',
        );
        stack.appendChild(error);
      },
    });

    stack.appendChild(image);
    root.appendChild(stack);
  },
);

Anchor to Add decorative branding imagesAdd decorative branding images

Mark non-essential images as decorative using accessibilityRole="decorative" with an empty accessibilityLabel. This example renders a partner branding banner that screen readers skip, keeping the focus on meaningful content.

Add decorative branding images

import {reactExtension, Image, Heading, Text, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {

return (

<Image

source="https://cdn.shopify.com/s/files/partner-branding/banner.png"

accessibilityLabel=""

accessibilityRole="decorative"

<Heading>Warehouse connection active</Heading>

<Text>

Your products are syncing automatically every 15 minutes with your

warehouse management system.

</Text>

</BlockStack>

);

}

export default reactExtension(

'admin.product-details.block.render',

() => <App />,

);

import {extension, Image, Heading, Text, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(

'admin.product-details.block.render',

(root) => {

const stack = root.createComponent(BlockStack);

const banner = root.createComponent(Image, {

source: 'https://cdn.shopify.com/s/files/partner-branding/banner.png',

accessibilityLabel: '',

accessibilityRole: 'decorative',

});

const heading = root.createComponent(

Heading,

{},

'Warehouse connection active',

);

const description = root.createComponent(

Text,

{},

'Your products are syncing automatically every 15 minutes with your warehouse management system.',

);

stack.appendChild(banner);

stack.appendChild(heading);

stack.appendChild(description);

root.appendChild(stack);

);

React

import {reactExtension, Image, Heading, Text, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {

  return (
    <BlockStack>
      <Image
        source="https://cdn.shopify.com/s/files/partner-branding/banner.png"
        accessibilityLabel=""
        accessibilityRole="decorative"
      />
      <Heading>Warehouse connection active</Heading>
      <Text>
        Your products are syncing automatically every 15 minutes with your
        warehouse management system.
      </Text>
    </BlockStack>
  );
}

export default reactExtension(
  'admin.product-details.block.render',
  () => <App />,
);

TS

import {extension, Image, Heading, Text, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.block.render',
  (root) => {

    const stack = root.createComponent(BlockStack);

    const banner = root.createComponent(Image, {
      source: 'https://cdn.shopify.com/s/files/partner-branding/banner.png',
      accessibilityLabel: '',
      accessibilityRole: 'decorative',
    });

    const heading = root.createComponent(
      Heading,
      {},
      'Warehouse connection active',
    );

    const description = root.createComponent(
      Text,
      {},
      'Your products are syncing automatically every 15 minutes with your warehouse management system.',
    );

    stack.appendChild(banner);
    stack.appendChild(heading);
    stack.appendChild(description);
    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

Write meaningful alt text: The required accessibilityLabel (or alt) prop is announced by screen readers and displayed when the image fails to load. Describe what the image shows, not how it looks — for example, "Product photo of a red wool scarf" rather than "image123.jpg". Learn more about writing effective alternative text.
Use decorative only for non-informational images: Set accessibilityRole="decorative" for background patterns, dividers, or visual flourishes that don't add meaning. If the image helps the merchant understand content or make a decision (like a product photo or a status illustration), then it needs alt text — don't mark it as decorative.

Anchor to LimitationsLimitations

Image doesn't support responsive image techniques like srcset or the picture element. A single image URL is used at all resolutions.
Image doesn't support built-in cropping, aspect ratio control, or object-fit behavior. The image renders at its natural size unless constrained by a parent container.

Was this page helpful?