hy-skeleton Skeleton Screen

A combination of placeholder graphics displayed while waiting for content to load, featuring animated loading effects to reduce user waiting anxiety.

📌 Platform Differences

APP(vue)	H5	WeChat Mini Program	Alipay Mini Program
✔	✔	✔	✔

⚠️ Notes

Notes

• The skeleton screen is displayed when the loading property is undefined or true; the slot content is displayed when it is false
• The rowCol property takes precedence over the theme property. If rowCol is set, the theme configuration will be ignored
• Animation effects add some performance overhead; it is recommended to disable animations in performance-sensitive scenarios
• The component supports virtual host and global styles, making it easy to integrate into existing projects

🏯 Basic Usage Example

The text theme is used by default, displaying a text skeleton screen.

<hy-skeleton />

Different Themes

Four themes are supported: text, avatar, paragraph, image.

Tip

• text: Text theme, displays a single line of text by default
• avatar: Avatar theme, displays a circular avatar
• image: Image theme, displays a rectangular image placeholder
• paragraph: Paragraph theme, displays multiple lines of text, with the last line at 55% width

<hy-skeleton theme="text" />
<hy-skeleton theme="avatar" />
<hy-skeleton theme="paragraph" />
<hy-skeleton theme="image" />

Loading State

Use the loading property to control the visibility of the skeleton screen. When loading is true, the skeleton screen is displayed; when it is false, the actual content is displayed.

<hy-skeleton :loading="loading">
    <view>Actual content</view>
</hy-skeleton>

Animation Effects

Two animation effects are supported: gradient (gradient loading animation) and flashed (flashing loading animation).

<hy-skeleton animation="gradient" />
<hy-skeleton animation="flashed" />

Custom Rows and Columns

The rowCol property allows you to customize the number of rows and columns, width, height, spacing, and more.

<!-- Example 1: Three-row skeleton, one column in the first row, one column in the second row, two columns in the third row -->
<hy-skeleton :rowCol="[1, 1, 2]" />

<!-- Example 2: Customize the third row's width to 100px -->
<hy-skeleton :rowCol="[1, 1, { width: '100px' }]" />

<!-- Example 3: Two columns in the third row, with custom width, height, and spacing -->
<hy-skeleton
    :rowCol="[1, 2, [{ width: '100px', height: '20px' }, { width: '200px', height: '20px', marginLeft: '10px' }]]"
/>

Complete Example

<template>
    <view>
        <hy-skeleton
            theme="avatar"
            :loading="loading"
            animation="gradient"
            :rowCol="[
        1,
        [
          { width: '24%', height: '16px', marginRight: '16px' },
          { width: '76%', height: '16px' }
        ]
      ]"
        >
            <view>Content after loading is complete</view>
        </hy-skeleton>
    </view>
</template>

<script setup>
    import { ref } from 'vue';

    const loading = ref(true);

    setTimeout(() => {
        loading.value = false;
    }, 2000);
</script>

API

Skeleton Props

Parameter	Description	Type	Default
theme	Skeleton style, optional values: text, avatar, paragraph, image	string	text
rowCol	Used to set the number of rows and columns, width and height, spacing, etc.	Array<number | SkeletonRowColObj | Array<SkeletonRowColObj>>	-
loading	Whether it is in loading state. When true, the skeleton screen is displayed; when false, the actual content is displayed	boolean	true
animation	Animation effect, optional values: gradient (gradient), flashed (flashing); empty means no animation	string	-
customStyle	External styles to be applied	CSSProperties	-
customClass	Custom external class name	string	-

Slots

Slot Name	Description	Value
default	Content displayed when loading is complete	-

Typings

::: detail Type Definitions

export type SkeletonTheme = 'text' | 'avatar' | 'paragraph' | 'image';
export type SkeletonAnimation = 'gradient' | 'flashed';
export type SkeletonRowColObj = {
    [key: string]: any;
    type?: 'rect' | 'circle' | 'text';
    size?: string | number;
    width?: string | number;
    height?: string | number;
    margin?: string | number;
    background?: string;
    marginLeft?: string | number;
    marginRight?: string | number;
    borderRadius?: string | number;
    backgroundColor?: string;
};
export type SkeletonRowCol = number | SkeletonRowColObj | Array<SkeletonRowColObj>;
export type SkeletonThemeVars = {
    notifyPadding?: string;
    notifyFontSize?: string;
    notifyTextColor?: string;
    notifyLineHeight?: number | string;
    notifyDangerBackground?: string;
    notifyPrimaryBackground?: string;
    notifySuccessBackground?: string;
    notifyWarningBackground?: string;
};

:::

CSS Variables

Variable	Description	Default
--hy-skeleton-height	Content placeholder height	20px
--hy-skeleton-circle-size	Circular avatar placeholder size	48px
--hy-skeleton-radius	Skeleton block border radius (text/col)	Follows --hy-radius-sm (8rpx)
--hy-skeleton-rect-radius	Rectangular skeleton border radius	Follows --hy-radius-base (20rpx)
--hy-skeleton-circle-radius	Circular skeleton border radius	Follows --hy-radius-circle (50%)

12:33