Van Back Top

Vant Back Top Component

A button component that allows users to quickly scroll back to the top of the page.

When to Invoke

Invoke this skill when:

• User needs to implement a back-to-top button
• User wants to show a button after scrolling down a certain distance
• User needs to customize the position of the back-to-top button
• User wants to scroll within a specific container
• User asks about scroll behavior or animation

Features

• Auto Show/Hide: Automatically shows after scrolling past a threshold
• Custom Position: Customize right and bottom distance
• Custom Content: Support custom button content via slots
• Target Container: Scroll within a specific container instead of window
• Immediate Scroll: Option for instant scrolling without animation
• Teleport: Mount to a specific DOM element
• Click Event: Custom click handler support

API Reference

Props

Events

Slots

Types

import type { BackTopProps, BackTopThemeVars } from 'vant';

Usage Examples

Basic Usage

<template>
  <div>
    <van-cell v-for="item in list" :key="item" :title="`Item ${item}`" />
    <van-back-top />
  </div>
</template>

<script setup>
import { ref } from 'vue';

const list = ref([...Array(50).keys()]);
</script>

Custom Position

<template>
  <div>
    <van-cell v-for="item in list" :key="item" :title="`Item ${item}`" />
    <van-back-top right="15vw" bottom="10vh" />
  </div>
</template>

<script setup>
import { ref } from 'vue';

const list = ref([...Array(50).keys()]);
</script>

Custom Content

<template>
  <div>
    <van-cell v-for="item in list" :key="item" :title="`Item ${item}`" />
    <van-back-top class="custom-back-top">Back Top</van-back-top>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const list = ref([...Array(50).keys()]);
</script>

<style>
.custom-back-top {
  width: 80px;
  font-size: 14px;
  text-align: center;
}
</style>

Scroll Within Container

<template>
  <div class="scroll-container">
    <van-cell v-for="item in list" :key="item" :title="`Item ${item}`" />
    <van-back-top target=".scroll-container" bottom="30vh" />
  </div>
</template>

<script setup>
import { ref } from 'vue';

const list = ref([...Array(50).keys()]);
</script>

<style>
.scroll-container {
  height: 60vh;
  overflow: auto;
}
</style>

Immediate Scroll

<template>
  <div>
    <van-cell v-for="item in list" :key="item" :title="`Item ${item}`" />
    <van-back-top immediate />
  </div>
</template>

<script setup>
import { ref } from 'vue';

const list = ref([...Array(50).keys()]);
</script>

With Click Event

<template>
  <div>
    <van-cell v-for="item in list" :key="item" :title="`Item ${item}`" />
    <van-back-top @click="handleClick" />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const list = ref([...Array(50).keys()]);

const handleClick = () => {
  showToast('Scrolled to top');
};
</script>

Best Practices

1. Set appropriate offset: Use offset prop to control when the button appears (default 200px)
2. Position carefully: Avoid overlapping with other fixed elements
3. Container scrolling: Use target prop for scrollable containers
4. Custom styling: Use slots for custom button appearance
5. Mobile optimization: Consider safe areas on iOS devices
6. Performance: Use immediate for instant scrolling on long pages