BackTop — Back to Top

17:06

Description

A back-to-top button that appears once the page scrolls past the top threshold and smoothly scrolls back to the top over duration. On App / H5 the component tracks page scroll itself, so binding scrollTop is unnecessary; WeChat Mini Program custom components cannot receive the page's onPageScroll, so listen in the page and pass scrollTop in manually. Supports two shapes (square / circle), a custom icon and hint text.

Compatibility

Platform	Support
App	✅ Supported (additionally supports `parentId` to scroll back to top inside a `scroll-view`)
H5	✅ Supported
WeChat Mini Program	✅ Supported (the component does not observe page scroll; pass the offset to `scroll-top` from the page's `onPageScroll`)

Examples

Basic Usage

After scrolling the page, a back-to-top button appears in the bottom-right corner. Tap it to smoothly scroll back to the top.

View source

vue

<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <!-- 页面滚动超过 200px 后显示返回顶部按钮 -->
        <ux-back-top :scroll-top="scrollTop" :top="200" />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

Custom Shape (shape)

shape="square" is a soft square with a small radius (4px, default), shape="circle" is a perfect circle. For a true sharp corner, inline border-radius: 0 via custom-style.

View source

vue

<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <!-- 两档形状全演示：square 小圆角（4px，不传即此档） / circle 正圆；
             组件为 position:fixed，靠 bottom/right 错开才能并排看到两个 -->
        <ux-back-top :scroll-top="scrollTop" :top="200" shape="square" tips="小圆角" :bottom="210" :right="20" />
        <ux-back-top :scroll-top="scrollTop" :top="200" shape="circle" tips="正圆" :bottom="210" :right="70" />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

Hint Text (tips)

Use the tips property to set the hint text below the button.

View source

vue

<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <ux-back-top :scroll-top="scrollTop" :top="200" tips="顶部" />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

Custom Position (bottom / right)

Adjust the button position with the bottom and right properties, in px units.

View source

vue

<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <ux-back-top :scroll-top="scrollTop" :top="200" :bottom="150" :right="100" />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

Custom Icon Style (icon-style)

Use the icon-style property to customize the icon's color and size.

View source

vue

<template>
    <view class="page-content">
        <view v-for="(item, index) in items" :key="index" class="scroll-item">
            <text>滚动内容 {{ index + 1 }}</text>
        </view>
        <ux-back-top
            :scroll-top="scrollTop"
            :top="200"
            :bottom="150"
            :right="150"
            :icon-style="{ color: '#2979ff', fontSize: '21px' }"
        />
    </view>
</template>

<script setup lang="uts">
const scrollTop = ref(0);
const items = ref<string[]>([]);
for (let i = 0; i < 20; i++) {
    items.value.push('item_' + i);
}

onPageScroll((e) => {
    scrollTop.value = e.scrollTop;
});
</script>

<style scoped>
.scroll-item {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
    border-radius: 6px;
    margin-bottom: 8px;
}
</style>

Scroll Test

Scroll down the page to observe the show/hide animation of the back-to-top button.

API

Props

Property	Description	Type	Default	Version
`customStyle`	Custom root element style	`string \| UTSJSONObject`	`-`	-
`customClass`	Custom root element style class	`string`	`''`	-
`shape`	Button shape (see `BackTopShape` in types/global.uts): square – small radius 4px (default) \| circle – perfect circle	`BackTopShape`	`'square'`	-
`icon`	Custom icon	`string`	`'arrow-upward'`	-
`tips`	Hint text	`string`	`''`	-
`duration`	Scroll duration when returning to top	`number \| string`	`100`	-
`scrollTop`	Scroll offset	`number \| string`	`0`	-
`top`	Scroll distance (px) after which the button appears	`number \| string`	`200`	-
`bottom`	Distance from the button to the bottom, in px	`number \| string`	`100`	-
`right`	Distance from the button to the right, in px	`number \| string`	`20`	-
`parentId`	Id of the App-side `scroll-view` container, for returning to top within a container; falls back to `uni.pageScrollTo` (page scroll) when omitted	`string`	`''`	-
`zIndex`	Stacking level	`number \| string`	`'9'`	-
`iconStyle`	Icon style, as an object	`UTSJSONObject`	`-`	-

Events

Event	Description	Params	Version
`click`	Fires when the button is tapped	-	-

Slots

Slot	Description	Version
`default`	Custom button content (defaults to the icon and hint text)	-

Notes

Display threshold: the button appears only once the scroll offset exceeds top (default 200px); top / bottom / right are all in px.
WeChat Mini Program custom components do not support the page's onPageScroll, so you must listen for scroll in the page and pass the offset to scroll-top; on App / H5 the component tracks page scroll itself, so no binding is needed.
parentId only takes effect on App, for when scrolling happens inside a scroll-view container (such as the demo page container); page-level scrolling needs none and uses uni.pageScrollTo.
There are only two shapes: square (4px small radius) and circle (perfect circle); for a sharp corner or another radius, inline border-radius via custom-style (inline wins over the shape class).
The component is position: fixed; when using several instances, offset them with bottom / right, or they will overlap.
icon-style accepts fontSize to change the icon size; when color is unset the icon falls back to the theme tips color.

BackTop — Back to Top ​

Description ​

Compatibility ​

Examples ​

Basic Usage ​

Custom Shape (shape) ​

Hint Text (tips) ​

Custom Position (bottom / right) ​

Custom Icon Style (icon-style) ​

Scroll Test ​

API ​

Props ​

Events ​

Slots ​

Notes ​

BackTop — Back to Top

Description

Compatibility

Examples

Basic Usage

Custom Shape (shape)

Hint Text (tips)

Custom Position (bottom / right)

Custom Icon Style (icon-style)

Scroll Test

API

Props

Events

Slots

Notes