Empty — Empty State

17:06

Description

A placeholder for empty content states, with a dozen built-in scenario icons (mode) and configurable text, colors and sizes. You can also point src at an icon or image directly, and a bottom slot lets you append an action button at the bottom.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Set the hint text with the text property and the icon type with the mode property.

View source

<template>
    <ux-empty text="暂无数据" mode="data" />
</template>

Built-in Icons & Text

Use the mode parameter to pick different scenario icons.

View source

<template>
    <view class="empty-icons">
        <view class="empty-icon-item"><ux-empty mode="car" /></view>
        <view class="empty-icon-item"><ux-empty mode="list" /></view>
        <view class="empty-icon-item"><ux-empty mode="search" /></view>
        <view class="empty-icon-item"><ux-empty mode="order" /></view>
        <view class="empty-icon-item"><ux-empty mode="address" /></view>
        <view class="empty-icon-item"><ux-empty mode="favor" /></view>
    </view>
</template>

<style scoped>
.empty-icons {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.empty-icon-item {
    width: 50%;
}
</style>

Custom Color & Size

Customize colors with color/icon-color and sizes with icon-size/font-size.

View source

<template>
    <ux-empty text="自定义颜色" mode="data" color="#2979ff" icon-color="#2979ff" :icon-size="80" :font-size="15" />
</template>

Custom Image (src)

Pass an image path via src; the mode parameter will then be ignored.

View source

<template>
    <ux-empty text="自定义图片" src="/static/logo.png" />
</template>

bottom Slot

Use the bottom slot to add custom content at the bottom of the component.

View source

<template>
    <ux-empty text="没有更多数据了">
        <template #bottom>
            <ux-button type="primary" size="small" shape="round" @click="onReload">重新加载</ux-button>
        </template>
    </ux-empty>
</template>

<script setup lang="uts">
const onReload = () => {
    uni.showToast({ title: '点击了重新加载', icon: 'none' });
};
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
src	Icon path	string	''	-
text	Hint text	string	''	-
color	Text color	string	''	-
iconColor	Icon color	string	''	-
iconSize	Icon size	string | number	DEFAULT_ICON_SIZE	-
fontSize	Text size, in px	string | number	DEFAULT_FONT_SIZE	-
mode	Selects a built-in icon type	EmptyMode	'data'	-
imgWidth	Icon width, in px	string | number	60	-
imgHeight	Icon height, in px	string | number	'auto'	-
show	Whether to show the component	boolean	true	-
marginTop	Distance between the component and the element above it	string | number	10	-

Events

ux-empty has no events.

Slots

Slot	Description	Version
bottom	Bottom slot of the component for extra custom content (such as a "Reload" button); it has a fixed top margin and is horizontally centered	-

Notes

1. src takes precedence over mode: once src is set, the built-in icon (mode) is ignored. src is forwarded to ux-icon, so a path containing / or a base64 string is rendered as an image and anything else is treated as an icon name.
2. img-width / img-height only take effect in src mode; they do not affect the built-in mode icons.
3. An empty text falls back to the built-in i18n copy for the given mode rather than showing no text.
4. icon-size / font-size follow a three-level priority: explicit value > global override (componentProps['ux-empty']) > built-in default (60 / 13).
5. With show=false the whole component is unmounted via v-if and renders no placeholder node.
6. The bottom slot has a fixed margin-top: 10px and is horizontally centered, so no extra spacing is needed inside the slot content.
7. mode comes from the EmptyMode union: car / page / search / address / wifi / order / coupon / favor / permission / history / news / message / list / data; the demo only shows 6 of them.