Skip to main content
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.

SkeletonImage

The SkeletonImage component provides a low-fidelity placeholder representation of an image before it appears on the page. Use SkeletonImage to maintain layout stability and reduce perceived loading time while images are being fetched.

Skeleton images support custom dimensions and aspect ratios to match the final loaded content. Combine with SkeletonText and SkeletonTextBlock for complete loading states.

Support
Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the SkeletonImage component.

Anchor to aspectRatio
aspectRatio
number

The aspect ratio to display the skeleton at (fills the width of the parent container and sets the height accordingly). Use this to reserve the correct space for an image before it loads, preventing content jumping.

Anchor to blockSize
blockSize
<number | `${number}%` | 'fill'>

The block size (height in horizontal writing modes) of the skeleton placeholder.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's block size.
  • fill: Takes all the available space.

Learn more about the block-size property.

Anchor to id
id
string

A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.

Anchor to inlineSize
inlineSize
<number | `${number}%` | 'fill'>

The inline size (width in horizontal writing modes) of the skeleton placeholder.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's inline size.
  • fill: Takes all the available space.

Learn more about the inline-size property.

Anchor to ExamplesExamples

Anchor to Display a skeleton placeholderDisplay a skeleton placeholder

Show a placeholder while an image loads. This example renders a 300x300 pixel skeleton image that reserves space for the final content.

Display a skeleton placeholder

A gray skeleton placeholder representing a loading image.

Display a skeleton placeholder

import {
reactExtension,
SkeletonImage,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<SkeletonImage
inlineSize={300}
blockSize={300}
/>
);
}
import {extension, SkeletonImage} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const skeletonImage = root.createComponent(SkeletonImage, {
inlineSize: 300,
blockSize: 300,
});

root.appendChild(skeletonImage);
});

Anchor to Prevent layout shifts during loadingPrevent layout shifts during loading

Incorporate skeleton loaders that match the size and position of the content during loading. This provides a seamless transition from skeleton loaders to the content and prevents layout shift when the resulting content loads.

Prevent layout shifts during loading

import {
reactExtension,
View,
BlockStack,
InlineLayout,
SkeletonImage,
Image,
Icon,
SkeletonText,
Text,
} from '@shopify/ui-extensions-react/checkout';

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

export const ProductThumbnail = ({
source = 'https://yourawesomeimage.com',
}) => (
<View
minBlockSize={64}
cornerRadius="large"
maxInlineSize={64}
minInlineSize={64}
border="base"
>
{source ? (
<Image
fit="cover"
aspectRatio={1}
source={source}
cornerRadius="large"
/>
) : (
<View maxInlineSize={33}>
<Icon source="camera" size="fill" />
</View>
)}
</View>
);
export const LoadingStateSkeletons = () => {
const loading = true;
const [item1, item2] = [
{
title: 'Felipe Toledo WildFire',
variantTitle: 'Medium',
price: '$330.00',
},
{
title: 'Roller',
variantTitle: 'Medium',
price: '$248.00',
},
];
const itemInfo = ({title, variantTitle}) =>
loading ? (
<>
<SkeletonText>{title}</SkeletonText>
<SkeletonText>
{variantTitle}
</SkeletonText>
</>
) : (
<>
<Text emphasis="bold">{title}</Text>
<Text appearance="subdued">
{variantTitle}
</Text>
</>
);
const order = (item) => (
<InlineLayout
columns={['auto', 'fill', 'auto']}
spacing="base"
blockAlignment="center"
>
{loading ? (
<SkeletonImage
blockSize={64}
inlineSize={64}
/>
) : (
<ProductThumbnail />
)}
<BlockStack spacing="extraTight">
{itemInfo(item)}
</BlockStack>
{loading ? (
<SkeletonText>{item.price}</SkeletonText>
) : (
<Text emphasis="bold">{item.price}</Text>
)}
</InlineLayout>
);
return (
<View maxInlineSize={400}>
<BlockStack>
{order(item1)}
{order(item2)}
</BlockStack>
</View>
);
};
import {
extension,
BlockStack,
View,
InlineLayout,
Image,
Icon,
Text,
SkeletonImage,
SkeletonText,
} from '@shopify/ui-extensions/checkout';

export default extension(
'purchase.checkout.block.render',
(root) => {
const source = 'https://yourawesomeimage.com';
const loading = true;
const [item1, item2] = [
{
title: 'Felipe Toledo WildFire',
variantTitle: 'Medium',
price: '$330.00',
},
{
title: 'Roller',
variantTitle: 'Medium',
price: '$248.00',
},
];
const thumbnail = root.createComponent(
View,
{
minBlockSize: 64,
cornerRadius: 'large',
maxInlineSize: 64,
minInlineSize: 64,
border: 'base',
},
[
source
? root.createComponent(Image, {
fit: 'cover',
aspectRatio: 1,
source,
cornerRadius: 'large',
})
: root.createComponent(
View,
{maxInlineSize: 33},
[
root.createComponent(Icon, {
source: 'camera',
size: 'fill',
}),
],
),
],
);
const itemInfo = ({title, variantTitle}) =>
root.createComponent(
BlockStack,
{
spacing: 'extraTight',
},
[
loading
? (root.createComponent(
SkeletonText,
{},
title,
),
root.createComponent(
SkeletonText,
{},
variantTitle,
))
: (root.createComponent(
Text,
{},
title,
),
root.createComponent(
Text,
{},
variantTitle,
)),
],
);
const order = (item) =>
root.createComponent(
InlineLayout,
{
columns: ['auto', 'fill', 'auto'],
spacing: 'base',
blockAlignment: 'center',
},
[
loading
? root.createComponent(
SkeletonImage,
{
blockSize: 64,
inlineSize: 64,
},
)
: thumbnail,
itemInfo(item),
loading
? root.createComponent(
SkeletonText,
{},
item.price,
)
: root.createComponent(
Text,
{},
item.price,
),
],
);
const view = root.createComponent(
View,
{
maxInlineSize: 400,
},
[
root.createComponent(BlockStack, {}, [
order(item1),
order(item2),
]),
],
);
root.appendChild(view);
},
);

Anchor to Set custom dimensionsSet custom dimensions

Create skeleton placeholders at different sizes and aspect ratios. This example shows three skeleton images with varying dimensions to demonstrate how inlineSize, blockSize, and aspectRatio control the placeholder shape.

Set custom dimensions

import {
reactExtension,
SkeletonImage,
InlineStack,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<InlineStack spacing="base">
<SkeletonImage inlineSize={64} blockSize={64} />
<SkeletonImage inlineSize={200} blockSize={150} />
<SkeletonImage inlineSize={100} aspectRatio={16 / 9} />
</InlineStack>
);
}
import {extension, SkeletonImage, InlineStack} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const row = root.createComponent(InlineStack, {spacing: 'base'});

row.append(root.createComponent(SkeletonImage, {inlineSize: 64, blockSize: 64}));
row.append(root.createComponent(SkeletonImage, {inlineSize: 200, blockSize: 150}));
row.append(root.createComponent(SkeletonImage, {inlineSize: 100, aspectRatio: 16 / 9}));

root.append(row);
});

Anchor to Best practicesBest practices

  • Match the skeleton to the final image size: Set the skeleton dimensions to closely approximate the loaded image so the layout doesn't shift when the real image appears.
  • Use for content that takes time to load: Display skeleton images when fetching remote images or processing data. Don't use them for content that's immediately available.
  • Combine with other skeleton components: Use skeleton images alongside SkeletonText and SkeletonTextBlock to create a cohesive loading experience.

Anchor to LimitationsLimitations

  • The skeleton image renders as a static placeholder. Animated shimmer effects aren't configurable.
  • The component doesn't automatically transition to the loaded image. You need to handle the loading state and swap the skeleton for the real image in your extension code.
Was this page helpful?