Toast

17:06

Description

An imperative light toast opened via show(options); it auto-dismisses when duration expires and can also be closed manually with hide() (alias close()). Supports a type theme, an icon toggle, a loading state and position (center / top / bottom); a callback runs after it closes, and it can navigate to a url or go back to the previous page.

Compatibility

Platform	Support
App	✅ Supported (native text does not inherit color/font-size from its parent, so the component declares them inline on the text; long-text width is capped at 525rpx, versus 70% on H5 / Mini Program)
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Tap the button to show a success toast that auto-dismisses after 2 seconds.

View source

<template>
    <ux-button type="primary" @click="showToast">成功提示</ux-button>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showToast = () => {
    toastRef.value?.show?.({
        title: '操作成功',
        type: 'success',
        duration: 2000
    });
};
</script>

Type

Supports primary/success/error/warning themes.

View source

<template>
    <view class="toast-row">
        <ux-button custom-class="toast-item" type="primary" size="small" @click="showType('primary')">primary</ux-button>
        <ux-button custom-class="toast-item" type="success" size="small" @click="showType('success')">success</ux-button>
        <ux-button custom-class="toast-item" type="error" size="small" @click="showType('error')">error</ux-button>
        <ux-button custom-class="toast-item" type="warning" size="small" @click="showType('warning')">warning</ux-button>
    </view>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showType = (type: string) => {
    toastRef.value?.show?.({
        title: '类型: ' + type,
        type,
        duration: 2000
    });
};
</script>

<style scoped>
.toast-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.toast-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

Position

Supports top, center and bottom positions.

View source

<template>
    <view class="toast-row">
        <ux-button custom-class="toast-item" type="success" size="small" @click="showPosition('top')">顶部</ux-button>
        <ux-button custom-class="toast-item" type="success" size="small" @click="showPosition('center')">居中</ux-button>
        <ux-button custom-class="toast-item" type="success" size="small" @click="showPosition('bottom')">底部</ux-button>
    </view>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showPosition = (position: string) => {
    toastRef.value?.show?.({
        title: '提示内容',
        position,
        type: 'success',
        duration: 2000
    });
};
</script>

<style scoped>
.toast-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.toast-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

Icon Toggle

Set icon=false to hide the icon.

View source

<template>
    <ux-button type="warning" size="small" @click="showNoIcon">不显示图标</ux-button>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showNoIcon = () => {
    toastRef.value?.show?.({
        title: '无图标提示',
        type: 'warning',
        icon: false,
        duration: 2000
    });
};
</script>

Loading Toast

Set loading=true to show a loading spinner.

View source

<template>
    <ux-button type="info" size="small" @click="showLoading">加载提示</ux-button>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showLoading = () => {
    toastRef.value?.show?.({
        title: '加载中...',
        type: 'default',
        duration: 2000,
        loading: true
    });
};
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom style for the root node	string | UTSJSONObject	-	-
customClass	Custom class for the root node	string	''	-
zIndex	Stacking z-index	string | number	''	-
type	Toast theme	ThemeType | 'default'	'default'	-
duration	Display duration, in ms	number	2000	-
icon	Whether to show the icon	boolean	true	-
position	Display position	ToastPosition	'center'	-
callback	Callback invoked on close	() => void	-	-
back	Whether to navigate back to the previous page	boolean	false	-
isTab	Whether the target is a tab page	boolean	false	-
url	URL to navigate to	string	''	-
params	Navigation params object	UTSJSONObject	-	-
global	Whether to act as a root-level toast	boolean	false	-
page	Whether to act as a page-level toast	boolean | string	false	-
loading	Whether it is a persistent loading toast	boolean	false	-

Events

ux-toast has no events.

Slots

ux-toast has no slots.

Notes

1. The component is driven through a ref: show(options) to display and hide() (alias close()) to hide.
2. When duration is 0 or ≤0 it does not auto-dismiss; call hide() / close() yourself.
3. icon only renders for the error / warning / success / info themes; primary / default show no icon even with icon=true.
4. With loading=true a loading spinner (ux-loading) replaces the icon, and icon is ignored.
5. callback only runs after the toast auto-dismisses when duration expires; a manual close with duration≤0 does not trigger it.
6. Calling show() again clears the previous timer and re-merges the options, so consecutive calls do not stack.
7. After duration expires, a non-empty url triggers uni.navigateTo, otherwise back=true navigates to the previous page; isTab currently does not affect navigation.
8. To show a toast as soon as a page opens, call show() in the onReady lifecycle.
9. The component uses ux-mask (transparent background, mask-click-able=false) as its base container and does not intercept page taps.