VuePress Back-to-Top Plugin

VuePress Back-to-Top Plugin provides a floating back-to-top button component for VuePress documentation sites. It features smooth scrolling animation, configurable visibility threshold, responsive design, and debounced scroll event handling for optimal performance.

Package Information

• Package Name: @vuepress/plugin-back-to-top
• Package Type: npm
• Language: JavaScript (Vue.js)
• Installation: npm install @vuepress/plugin-back-to-top

Core Imports

This is a VuePress plugin, so it's primarily configured in VuePress config files rather than imported directly:

// .vuepress/config.js
module.exports = {
  plugins: ['@vuepress/plugin-back-to-top']
}

For advanced configurations:

// .vuepress/config.js
module.exports = {
  plugins: [
    ['@vuepress/plugin-back-to-top', {
      // Plugin currently accepts no configuration options
    }]
  ]
}

Basic Usage

Simply add the plugin to your VuePress configuration. The plugin automatically:

1. Registers a global BackToTop Vue component
2. Adds the component to all pages as a fixed-position UI element
3. Shows/hides the button based on scroll position (default threshold: 300px)
4. Provides smooth scrolling when clicked

// .vuepress/config.js
module.exports = {
  title: 'My VuePress Site',
  description: 'My documentation site',
  plugins: [
    '@vuepress/plugin-back-to-top'
  ]
}

Architecture

The plugin follows VuePress's plugin architecture with these key components:

• Plugin Definition: Main plugin object that integrates with VuePress
• Vue Component: BackToTop.vue component providing the UI and behavior
• App Enhancement: Registration hook that makes the component globally available
• Global UI Integration: Automatic inclusion on all pages without manual placement

Capabilities

Plugin Configuration

The main plugin entry point that integrates with VuePress.

/**
 * VuePress plugin object for back-to-top functionality
 * @type {import('@vuepress/types').Plugin}
 */
module.exports = {
  enhanceAppFiles: string[];
  globalUIComponents: string;
};

/**
 * Plugin options interface (currently empty)
 */
interface PluginConfig4BackToTop {}

The plugin object contains:

• enhanceAppFiles: Array pointing to the app enhancement file
• globalUIComponents: String specifying 'BackToTop' as a global UI component

BackToTop Vue Component

The main UI component that renders the back-to-top button.

/**
 * BackToTop Vue component
 */
interface BackToTopComponent {
  name: 'BackToTop';
  props: {
    threshold: {
      type: Number;
      default: 300;
    };
  };
  data(): {
    scrollTop: number | null;
  };
  computed: {
    show(): boolean;
  };
  methods: {
    getScrollTop(): number;
    scrollToTop(): void;
  };
  mounted(): void;
}

/**
 * Template interface - SVG-based back-to-top button
 */
interface BackToTopTemplate {
  /** Click handler for scrolling to top */
  '@click': 'scrollToTop';
  /** Conditional visibility based on show computed property */
  'v-if': 'show';
  /** CSS class applied to the SVG element */
  class: 'go-to-top';
  /** Fade transition wrapper */
  transition: 'fade';
}

Props:

• threshold: Number - Scroll position in pixels after which the button becomes visible (default: 300)

Data Properties:

• scrollTop: Current scroll position in pixels

Computed Properties:

• show: Boolean indicating whether the button should be visible (based on scroll position vs threshold)

Methods:

• getScrollTop(): Returns current scroll position from window, document, or body
• scrollToTop(): Scrolls to top of page with smooth behavior and resets scrollTop to 0

Lifecycle Hooks:

• mounted(): Sets up initial scroll position and adds debounced scroll event listener to window

App Enhancement Function

Registers the BackToTop component globally in the Vue application.

/**
 * VuePress app enhancement function
 * @param {Object} context - VuePress app context
 * @param {Vue} context.Vue - Vue constructor
 */
function enhanceApp({ Vue }: { Vue: any }): void;

This function is automatically called by VuePress and registers the BackToTop component globally, making it available as <BackToTop/> in all Vue templates.

Technical Implementation Details

Component Features

• Smooth Scrolling: Uses window.scrollTo({ top: 0, behavior: 'smooth' })
• Debounced Scroll Handling: Scroll events are debounced to 100ms using lodash.debounce
• Responsive Design: Hidden on mobile devices (screen width < 959px)
• Fade Animations: CSS transitions for smooth show/hide effects
• Cross-browser Compatibility: Fallback scroll position detection for different browsers

Styling

• Fixed position at bottom-right corner (2rem from bottom, 2.5rem from right)
• SVG arrow icon with hover effects
• Color uses VuePress theme's $accentColor variable
• 2rem width with proper z-index for overlay positioning

CSS Classes:

• .go-to-top: Main button styling (fixed position, cursor, color, dimensions)
• .go-to-top:hover: Hover state with lighter accent color
• .fade-enter-active, .fade-leave-active: Transition animation classes (0.3s opacity)
• .fade-enter, .fade-leave-to: Fade animation states (opacity: 0)

Dependencies

• @vuepress/types: TypeScript definitions for VuePress plugin API
• lodash.debounce: Scroll event throttling
• @vuepress/shared-utils: Path utilities for file resolution

Error Handling

The plugin is designed to be fault-tolerant:

• Graceful fallbacks for scroll position detection across browsers
• No error throwing - component will simply not show if there are issues
• Automatic cleanup of scroll listeners when component is destroyed

Types

// VuePress Plugin Types
interface Plugin<T = any, U = any> {
  enhanceAppFiles?: string | string[];
  globalUIComponents?: string | string[];
}

interface PluginConfig4BackToTop {}

// Component Props Interface
interface BackToTopProps {
  threshold?: number;
}

// Vue Component Data Interface
interface BackToTopData {
  scrollTop: number | null;
}

// App Enhancement Context
interface EnhanceAppContext {
  Vue: any;
}