---
title: Image
description: >-
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.
api_version: 2025-07
api_name: pos-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/pos-ui-extensions/2025-07/ui-components/media-and-visuals/image
md: >-
https://shopify.dev/docs/api/pos-ui-extensions/2025-07/ui-components/media-and-visuals/image.md
---
# 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
* [pos.cart.line-item-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/cart-details#cart-details-action-modal-)
* [pos.customer-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/customer-details#customer-details-action-modal-)
* [pos.customer-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/customer-details#customer-details-block-)
* [pos.draft-order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/draft-order-details#draft-order-details-action-modal-)
* [pos.draft-order-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/draft-order-details#draft-order-details-block-)
* [pos.exchange.post.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-exchange#post-exchange-action-modal-)
* [pos.exchange.post.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-exchange#post-exchange-block-)
* [pos.home.modal.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/home-screen#home-screen-action-modal-)
* [pos.order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/order-details#order-details-action-modal-)
* [pos.order-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/order-details#order-details-block-)
* [pos.product-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/product-details#product-details-action-modal-)
* [pos.product-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/product-details#product-details-block-)
* [pos.purchase.post.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-purchase#post-purchase-action-modal-)
* [pos.purchase.post.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-purchase#post-purchase-block-)
* [pos.return.post.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-return#post-return-action-modal-)
* [pos.return.post.block.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/post-return#post-return-block-)
#### Use cases
* **Product images:** Display product images in catalogs and order details for quick identification.
* **Promotional content:** Show promotional banners or marketing materials.
* **Visual instructions:** Provide visual instructions or onboarding content for complex processes.
* **Brand consistency:** Display logos or branding elements to maintain brand consistency.
## Examples
### Show 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
### Examples
* #### Show an image
##### Description
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.
##### React
```tsx
import React from 'react';
import {
Image,
Screen,
ScrollView,
Navigator,
Box,
reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';
const SmartGridModal = () => {
return (
);
};
export default reactExtension('pos.home.modal.render', () => (
));
```
##### TS
```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);
});
```
## Properties
Configure the following properties on the `Image` component.
* size
ImageSize | FillResizeMode
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.
* 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
```ts
'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.
```ts
'cover' | 'contain' | 'stretch' | 'repeat' | 'center'
```
## Best 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.
## Limitations
* 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.