TopTips

17:06

Description

A lightweight tip that slides in at the top of the page. Trigger it through the component instance with show({ title, type, duration }) and it hides itself after the duration. It automatically avoids the status bar and custom navbar, or you can set navbarHeight explicitly; supports primary / success / warning / error / info themes.

Compatibility

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

Examples

Basic Usage

Call show() through the component ref; defaults to the primary theme and hides after 2 seconds.

View source

<template>
    <ux-button type="primary" shape="round" text="弹出提示" @click="showBasic" />
    <ux-top-tips ref="tipsRef" />
</template>

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

const showBasic = () => {
    tipsRef.value?.show?.({
        title: '这是一条顶部提示'
    });
};
</script>

Theme

show({ type }) supports primary / success / warning / error / info themes.

View source

<template>
    <view class="top-tips-row">
        <ux-button custom-class="top-tips-item" type="primary" size="small" shape="round" text="primary 主题" @click="showType('primary')" />
        <ux-button custom-class="top-tips-item" type="success" size="small" shape="round" text="success 主题" @click="showType('success')" />
        <ux-button custom-class="top-tips-item" type="warning" size="small" shape="round" text="warning 主题" @click="showType('warning')" />
        <ux-button custom-class="top-tips-item" type="error" size="small" shape="round" text="error 主题" @click="showType('error')" />
        <ux-button custom-class="top-tips-item" type="info" size="small" shape="round" text="info 主题" @click="showType('info')" />
    </view>
    <ux-top-tips ref="tipsRef" />
</template>

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

const showType = (type: string) => {
    tipsRef.value?.show?.({
        title: '这是一条顶部提示',
        type
    });
};
</script>

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

Duration

show({ duration }) controls how long the tip stays visible in milliseconds.

View source

<template>
    <view class="top-tips-row">
        <ux-button custom-class="top-tips-item" type="primary" size="small" shape="round" text="停留 1 秒" @click="showDuration(1000)" />
        <ux-button custom-class="top-tips-item" type="primary" size="small" shape="round" text="停留 3 秒" @click="showDuration(3000)" />
    </view>
    <ux-top-tips ref="tipsRef" />
</template>

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

const showDuration = (duration: number) => {
    tipsRef.value?.show?.({
        title: '这是一条顶部提示',
        duration
    });
};
</script>

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

Navbar Height & z-index

navbar-height adapts to the page navbar height in px; z-index controls the stacking level.

View source

<template>
    <ux-button type="warning" shape="round" text="从导航栏下方弹出" @click="showNav" />
    <ux-top-tips ref="tipsRef" :navbar-height="navBarHeight" :z-index="9999" />
</template>

<script setup lang="uts">
import { useWindowInfo, useDeviceInfo } from '@/uni_modules/uview-pro-x';

const { statusBarHeight } = useWindowInfo();
const { platform } = useDeviceInfo();

const tipsRef = ref<any>();

// 顶部避让总高度 = 状态栏 + 自绘导航栏本体（取法与页面 ux-navbar 默认高度一致）
const navBarHeight = computed((): number => {
    let body = 44;
    // #ifdef MP
    body = platform.value == 'ios' ? 44 : 48;
    // #endif
    return statusBarHeight.value + body;
});

const showNav = () => {
    tipsRef.value?.show?.({
        title: '已适配导航栏高度',
        duration: 3000
    });
};
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom style for the root node	String	''	-
customClass	Custom class for the root node	String	''	-
navbarHeight	Total top offset including the status bar, in px. When 0 (default) it is computed as status bar + platform navbar height (App/H5 44; Mini Program iOS 44 / Android 48; H5 has no status bar, so 44), so the tip appears right below a custom navbar	Number|String	0	-
zIndex	Tip z-index; defaults to $u.zIndex.topTips	Number|String	-	-

Events

ux-top-tips has no events.

Slots

ux-top-tips has no slots.

Notes

1. Trigger it only through the instance show() — there is no show prop or v-model. Calling show() again clears the previous timer and restarts the countdown.
2. Omitting type / duration reuses the previous values (initially primary / 2000ms); they are not reset to defaults on every call.
3. With navbarHeight=0 (default), the offset is status bar + navbar: App and H5 use 44, Mini Program uses 44 on iOS and 48 on Android; H5 has no system status bar, so the result is 44. Pages with a custom navbar can pass the full offset explicitly.
4. While hidden, z-index is -1; the configured zIndex (default $u.zIndex.topTips) applies only while visible, so it does not cover other page elements.
5. WeChat Mini Program disables the persistent transition; the entrance uses a one-shot keyframes animation instead, so timing details differ slightly from other platforms.