n-back-top

Back Top component for scrolling back to page top. Invoke when user needs to implement a back-to-top button or scroll-to-top functionality in Naive UI.

SKILL.md

GitHub

Naive UI Back Top Component

It helps you back to where you were. However, time never goes back.

When to Use

Use this component when:

  • Long pages: Provide quick navigation back to top
  • Infinite scroll: Allow users to return to top after scrolling deep
  • Documentation sites: Easy navigation for long documentation pages
  • E-commerce: Quick return to top after browsing products

When to Invoke

Invoke this skill when:

  • User needs to implement a back-to-top button
  • User wants to customize back-to-top appearance
  • User needs to control visibility based on scroll height
  • User wants to target a specific scrollable container
  • User asks about scroll-to-top functionality

Features

  • Auto Detection: Automatically finds first scrollable ancestor
  • Visibility Control: Show/hide based on scroll height threshold
  • Custom Position: Configurable right and bottom positioning
  • Custom Content: Fully customizable button content
  • Target Listening: Listen to specific scrollable elements

API Reference

BackTop Props

Name Type Default Description
bottom number | string 40 The height of BackTop from the bottom of the page
listen-to string | HTMLElement undefined The element to be listened to scroll event. If it is undefined back top will listen to the nearest scrollable parent.
right number | string 40 The width of BackTop from the right side of the page
show boolean undefined Whether to show BackTop
to string | HTMLElement 'body' Container node to show BackTop
visibility-height number 180 BackTop's trigger scroll top.
on-update:show (value: boolean) => void undefined Callback is triggered when back-top display changes.

Basic Usage

Basic Back Top

<template>
  <n-back-top :right="100" />
</template>

Custom Visibility Height

<template>
  <n-back-top
    :bottom="100"
    :visibility-height="300"
    :style="{
      transition: 'all .3s cubic-bezier(.4, 0, .2, 1)',
    }"
  >
    <div
      style="
        width: 200px;
        height: 40px;
        line-height: 40px;
        text-align: center;
        font-size: 14px;
      "
    >
      Visibility Height: 300px
    </div>
  </n-back-top>
</template>

Custom Position

<template>
  <n-back-top
    :right="40"
    :bottom="160"
    :style="{
      transition: 'all .3s cubic-bezier(.4, 0, .2, 1)',
    }"
  >
    <div
      style="
        width: 200px;
        height: 40px;
        line-height: 40px;
        text-align: center;
        font-size: 14px;
      "
    >
      Change Position
    </div>
  </n-back-top>
</template>

Common Patterns

Target Specific Container

<template>
  <n-back-top
    :listen-to="target"
    :bottom="220"
    :visibility-height="10"
    :style="{
      transition: 'all .3s cubic-bezier(.4, 0, .2, 1)',
    }"
  >
    <div
      style="
        width: 200px;
        height: 40px;
        line-height: 40px;
        text-align: center;
        font-size: 14px;
      "
    >
      Specify Target
    </div>
  </n-back-top>
  <div
    ref="scrollContainer"
    style="overflow: auto; height: 72px; line-height: 1.5"
  >
    <p v-for="i in 10" :key="i">
      Scroll content line {{ i }}
    </p>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'

const scrollContainer = ref(null)
const target = computed(() => scrollContainer.value)
</script>

Custom Icon Back Top

<template>
  <n-back-top :right="40" :bottom="80">
    <n-button circle size="large">
      <template #icon>
        <n-icon><ArrowUpIcon /></n-icon>
      </template>
    </n-button>
  </n-back-top>
</template>

Controlled Visibility

<template>
  <n-back-top :show="isVisible" @update:show="handleShowChange" />
</template>

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

const isVisible = ref(false)

const handleShowChange = (value) => {
  isVisible.value = value
}
</script>

Best Practices

  1. Set appropriate visibility-height: Show button only after meaningful scroll distance

  2. Position for accessibility: Position where it won't obstruct content but is easily accessible

  3. Customize for branding: Match button style with your application theme

  4. Use with specific containers: Set listen-to for scrollable containers other than document

  5. Smooth transitions: Add CSS transitions for better user experience

  6. Mobile considerations: Adjust position for mobile devices to avoid obstruction