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 adds visual content within the interface and allows you to customize the presentation of visuals. Use images to showcase products, illustrate concepts, provide visual context, or support user tasks and interactions in POS workflows.

Images enhance the user experience by providing immediate visual recognition and reducing cognitive load.

Image components handle loading errors gracefully with fallback options and provides placeholder states to maintain layout stability during image loading on slower network connections. The component implements lazy loading for images outside the viewport, improving initial page load performance while ensuring smooth scrolling as merchants navigate through product catalogs or image-heavy interfaces.

Support

Targets (16)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Image component.

Anchor to size size | Default: 'l': The size or fill behavior of the image. Use ImageSize values ('s', 'm', 'l', 'xl') for fixed dimensions, or FillResizeMode values ('cover', 'contain', 'stretch', 'repeat', 'center') to control how the image fills its container.
Anchor to src src string: The source of the image to be displayed. Provide a valid URL to a remote image or a local file resource. When no src is provided or the image is loading, a placeholder will be rendered.

ImageSize

's' | 'm' | 'l' | 'xl'

FillResizeMode

Defines how images are resized and positioned within their containers. Controls image scaling, cropping, and aspect ratio handling. Available resize modes: - `center`: Centers the image within its container without scaling. The image maintains its original size and is positioned in the center, potentially leaving empty space or being cropped if the container is smaller. - `contain`: Scales the image to fit entirely within the container while maintaining aspect ratio. The entire image will be visible, but there may be empty space if the aspect ratios don't match. - `cover`: Scales the image to fill the entire container while maintaining aspect ratio. Parts of the image may be cropped if the aspect ratios don't match, but the container will be completely filled. - `repeat`: Repeats the image to fill the container. The image maintains its original size and is tiled both horizontally and vertically to cover the entire container area. - `stretch`: Stretches the image to fill the container completely, potentially distorting the aspect ratio. The image will fill the entire container but may appear stretched or compressed.

'cover' | 'contain' | 'stretch' | 'repeat' | 'center'

Anchor to ExamplesExamples

Anchor to Show an imageShow an image

Show images within your extension interface with customizable presentation. This example demonstrates rendering images with proper sizing, loading states, and error handling, ideal for showcasing products, illustrating concepts, or providing visual context in POS workflows.

Show an image

import React from 'react';

import {

Image,

Screen,

ScrollView,

Navigator,

Box,

reactExtension,

} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {

return (

</Box>

</ScrollView>

</Screen>

</Navigator>

);

};

export default reactExtension('pos.home.modal.render', () => (

));

import {

Navigator,

Screen,

ScrollView,

Image,

extension,

Box,

} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {

const image = root.createComponent(Image, {

src: 'example.png',

size: 's',

});

const filledImage = root.createComponent(Image, {

src: 'example.png',

size: 'cover',

});

const scrollView = root.createComponent(ScrollView);

scrollView.append(image);

const box = scrollView.createComponent(Box, {

blockSize: '600px',

inlineSize: '600px',

padding: '400',

});

box.append(filledImage);

scrollView.append(box);

const screen = root.createComponent(Screen, {

name: 'Image',

title: 'Image Example',

});

screen.append(scrollView);

const navigator = root.createComponent(Navigator);

navigator.append(screen);

root.append(navigator);

});

React

import React from 'react';

import {
  Image,
  Screen,
  ScrollView,
  Navigator,
  Box,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {
  return (
    <Navigator>
      <Screen name="Image" title="Image Example">
        <ScrollView>
          <Image src="example.png" size="s" />
          <Box blockSize="600px" inlineSize="600px" padding="400">
            <Image src="example.png" size="cover" />
          </Box>
        </ScrollView>
      </Screen>
    </Navigator>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

TS

import {
  Navigator,
  Screen,
  ScrollView,
  Image,
  extension,
  Box,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
  const image = root.createComponent(Image, {
    src: 'example.png',
    size: 's',
  });

  const filledImage = root.createComponent(Image, {
    src: 'example.png',
    size: 'cover',
  });

  const scrollView = root.createComponent(ScrollView);
  scrollView.append(image);

  const box = scrollView.createComponent(Box, {
    blockSize: '600px',
    inlineSize: '600px',
    padding: '400',
  });

  box.append(filledImage);
  scrollView.append(box);

  const screen = root.createComponent(Screen, {
    name: 'Image',
    title: 'Image Example',
  });
  screen.append(scrollView);

  const navigator = root.createComponent(Navigator);
  navigator.append(screen);

  root.append(navigator);
});

Anchor to Best practicesBest practices

Select the right fill behavior: Use 'contain' when showing the complete image is important, 'cover' when filling the container is more important than showing the entire image, and 'stretch' only when exact container filling is required regardless of distortion.
Optimize image sources: Ensure image URLs are properly formatted, properly formatted, and optimized for web delivery. Consider image compression, appropriate file formats, and loading performance when selecting image sources.
Plan for loading states: The component automatically shows placeholders during loading or when no src is provided. Design your layouts to accommodate these loading states and ensure they don't negatively impact the user experience.
Consider responsive design: Choose size values that work well across different screen sizes and device orientations. Test your image layouts on various POS devices.

Anchor to LimitationsLimitations

Images are display-only components and don't support click events or interactive behaviors.
Image loading and caching behavior depends on the browser and network conditions—implement proper error handling for better user experience.
Large images can impact performance—ensure proper optimization and consider the device capabilities of your target POS hardware.

Was this page helpful?