🌏 Translated with the assistance of DeepSeek and ChatGPT

BackTop

Back to where it all began.

Basic Usage

The component can be placed anywhere within the application and, by default, listens to the scroll events of the window.

The visibilityHeight parameter sets the distance from the top of the scroll container, with a default value of 200px. The BackTop component only becomes visible once this distance is reached.

The right and bottom properties set the distance of the component's content from the right and bottom edges of the viewport, respectively.

Scroll down to see the BackTop button

<template>
	<div>
		<h3>Scroll down to see the BackTop button</h3>
		<px-back-top />
		<px-back-top :visibility-height="400" :right="120" />
	</div>
</template>

Custom Button & Icon

Customize the inner button by passing buttonProps or provide your own default slot to replace the whole content. Use the icon slot to customize the icon.

Customize the inner button with buttonProps and replace the icon via the icon slot.

<template>
	<div>
		<p>
			Customize the inner button with <code>buttonProps</code> and replace the icon via the
			<code>icon</code> slot.
		</p>
		<px-back-top :button-props="{ theme: 'primary', shape: 'circle' }" :bottom="100">
			<template #icon>
				<IconArrowUp />
			</template>
		</px-back-top>
		<px-back-top :bottom="160">
			<template #trigger>
				<px-button> Scroll to Top! </px-button>
			</template>
		</px-back-top>
	</div>
</template>

<script setup lang="ts">
import { IconArrowUp } from '@pixelium/web-vue/icon-pa/es'
</script>

Custom Root Container

By setting root to a selector or an HTMLElement, you can make the component listen to a specific scrollable container instead of window.

💡 Tip: When root is a CSS selector string, it will be resolved with document.querySelector. If no element matches, the component falls back to window.

Scrollable container below. BackTop listens to the container when root is set.

This container is scrollable — scroll inside it to trigger the BackTop button.

<template>
	<div>
		<p>
			Scrollable container below. BackTop listens to the container when <code>root</code> is
			set.
		</p>
		<div
			class="scroll-root"
			style="height: 220px; overflow: auto; border: 1px solid var(--px-neutral-6)"
		>
			<div style="height: 800px; background: linear-gradient(180deg, #fff, #f4f7fb)">
				<p style="padding: 12px">
					This container is scrollable — scroll inside it to trigger the BackTop button.
				</p>
			</div>
		</div>
		<!-- BackTop will listen to the .scroll-root element -->
		<px-back-top root=".scroll-root" :bottom="220">
			<template #trigger>
				<px-button theme="warning"> Custom Root ↑</px-button>
			</template>
		</px-back-top>
	</div>
</template>

API

BackTopProps

Attribute	Type	Optional	Default	Description	Version
root	HTMLElement | string | Window	True	Window	The scroll container, which can be an HTMLElement, CSS selector string, or window; defaults to listening to window.	0.1.0
visibilityHeight	number	True	200	The scroll height threshold (px) at which the button becomes visible.	0.1.0
right	number	True	40	Offset from the right side of the viewport (px).	0.1.0
bottom	number	True	40	Offset from the bottom of the viewport (px).	0.1.0
zIndex	number	True	1000	The z-index value for the component's style.	0.1.0
buttonProps	ButtonProps & EmitEvent<ButtonEvents> & RestAttrs	True		Props passed to the internal Button component (effective when the trigger slot is not used).	0.1.0

BackTopSlots

Slot	Parameter	Description	Version
trigger		Custom content for the entire back-to-top button.	0.1.0
icon		Custom internal icon (effective when the trigger slot is not used).	0.1.0

RestAttrs

import type { StyleValue } from 'vue'

export type VueClassValue = string | Record<string, any> | VueClassValue[]
export type VueStyleValue = StyleValue

export type RestAttrs = {
	style?: VueStyleValue | null
	class?: VueClassValue | null
	[x: string]: any
}

EmitEvent

export type EmitEvent<T extends Record<string, any>> = {
	[K in keyof T as `on${Capitalize<K & string>}`]?: (...args: T[K]) => void
}