Backtop

A shortcut button that triggers smooth scrolling back to the top of its viewport. Features custom throttle protections on scroll events and classical brutalist card layouts.

Preview

Preview

基础用法

向下滚动下方容器，当滚动距离超过 100px 时，容器右下角会出现回到顶部按钮。 指定 target 后，Backtop 使用 absolute 定位，按钮会相对目标容器定位，不会逃出预览框。

滚动内容

向下滚动以触发回到顶部按钮

Installation

pnpm dlx brutx-vue@latest add backtop

Usage

Basic Global Usage

Include <Backtop> inside your main wrapper template. The shortcut button appears automatically once page scroll offset passes 200px.

<script setup>
import { Backtop } from 'brutx-ui-vue'
</script>

<template>
    <Backtop :visibility-height="200" />
</template>

Local Target Scroll Container

Target scroll containers that have overflow-y: auto by assigning the selector ID or element reference to the target prop.

<template>
    <div id="my-scroll-box" class="h-60 overflow-y-auto relative">
        <div class="h-[800px]">...</div>
        
        <!-- target binds element selector -->
        <Backtop target="#my-scroll-box" :visibility-height="100" />
    </div>
</template>

Custom Positioning and Themes

Apply customized alignment offsets via right or bottom coordinates, and toggle color layouts by modifying variant.

<template>
    <Backtop 
        :right="80" 
        :bottom="80" 
        variant="accent" 
        :visibility-height="150" 
    />
</template>

API Reference

Backtop — Props

Name	Type	Default	Description
visibilityHeight	number | undefined	200	Shows the button when the scroll container reaches this vertical scroll distance in pixels.
Details Declared type number | undefined Default value details Declaration 200 Source: packages/ui/src/components/backtop/Backtop.vue Resolved value 200 Source Backtop.vue:14 packages/ui/src/components/backtop/Backtop.vue
target	string | HTMLElement | undefined	undefined Runtime fallback:When omitted or an empty string, observes window and fixes the button to the viewport.	The container to observe and scroll to the top, supplied as a CSS selector or element. Setting it uses absolute button positioning and requires a positioned ancestor.
Details Declared type string | HTMLElement | undefined Default value details Declaration undefined Source: packages/ui/src/components/backtop/Backtop.vue Resolved value undefined Runtime fallback When omitted or an empty string, observes window and fixes the button to the viewport. Applied by the component under the documented runtime conditions. Source Backtop.vue:15 packages/ui/src/components/backtop/Backtop.vue
right	number | undefined	40	The distance from the right edge of the positioning area, in pixels.
Details Declared type number | undefined Default value details Declaration 40 Source: packages/ui/src/components/backtop/Backtop.vue Resolved value 40 Source Backtop.vue:16 packages/ui/src/components/backtop/Backtop.vue
bottom	number | undefined	40	The distance from the bottom edge of the positioning area, in pixels.
Details Declared type number | undefined Default value details Declaration 40 Source: packages/ui/src/components/backtop/Backtop.vue Resolved value 40 Source Backtop.vue:17 packages/ui/src/components/backtop/Backtop.vue
variant	"default" | "ghost" | "primary" | "secondary" | "success" | "danger" | "accent" | "outline" | "link" | undefined	"primary"	The visual variant passed to the inner Button. The primary variant also applies a yellow background and black text.
Details Declared type "default" | "ghost" | "primary" | "secondary" | "success" | "danger" | "accent" | "outline" | "link" | undefined Literal values "accent" "danger" "default" "ghost" "link" "outline" "primary" "secondary" "success" Default value details Declaration 'primary' Source: packages/ui/src/components/backtop/Backtop.vue Resolved value "primary" Source Backtop.vue:18 packages/ui/src/components/backtop/Backtop.vue
class	string | undefined	undefined	Custom CSS classes added to the back-to-top button.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/backtop/Backtop.vue Resolved value undefined Source Backtop.vue:19 packages/ui/src/components/backtop/Backtop.vue

Backtop — Events

Name	Signature or type	Description
@click	[event: MouseEvent]	Emits the original mouse event when clicked, then requests a smooth scroll to the top of the target container.
Details Declared type [event: MouseEvent] Source Backtop.vue packages/ui/src/components/backtop/Backtop.vue

Backtop — Slots

Name	Signature or type	Description
#default	{}	Replaces the upward arrow inside the button.
Details Declared type {} Source Backtop.vue packages/ui/src/components/backtop/Backtop.vue

Accessibility

• Keyboard: The button supports focus with Tab and activation with Enter or Space.
• ARIA Semantics: The button uses the localized backtop.backToTop message as its accessible name.
• Scrolling: Activation requests native scrolling with { top: 0, behavior: 'smooth' }; the browser controls the resulting scrolling behavior.