0
# VuePress Back-to-Top Plugin
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @vuepress/plugin-back-to-top
7
- **Package Type**: npm
8
- **Language**: JavaScript (Vue.js)
9
- **Installation**: `npm install @vuepress/plugin-back-to-top`
10

11
## Core Imports
12

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

15
```javascript
16
// .vuepress/config.js
17
module.exports = {
18
  plugins: ['@vuepress/plugin-back-to-top']
19
}
20
```
21

22
For advanced configurations:
23

24
```javascript
25
// .vuepress/config.js
26
module.exports = {
27
  plugins: [
28
    ['@vuepress/plugin-back-to-top', {
29
      // Plugin currently accepts no configuration options
30
    }]
31
  ]
32
}
33
```
34

35
## Basic Usage
36

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

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

44
```javascript
45
// .vuepress/config.js
46
module.exports = {
47
  title: 'My VuePress Site',
48
  description: 'My documentation site',
49
  plugins: [
50
    '@vuepress/plugin-back-to-top'
51
  ]
52
}
53
```
54

55
## Architecture
56

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

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

64
## Capabilities
65

66
### Plugin Configuration
67

68
The main plugin entry point that integrates with VuePress.
69

70
```javascript { .api }
71
/**
72
 * VuePress plugin object for back-to-top functionality
73
 * @type {import('@vuepress/types').Plugin}
74
 */
75
module.exports = {
76
  enhanceAppFiles: string[];
77
  globalUIComponents: string;
78
};
79

80
/**
81
 * Plugin options interface (currently empty)
82
 */
83
interface PluginConfig4BackToTop {}
84
```
85

86
The plugin object contains:
87
- `enhanceAppFiles`: Array pointing to the app enhancement file
88
- `globalUIComponents`: String specifying 'BackToTop' as a global UI component
89

90
### BackToTop Vue Component
91

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

94
```javascript { .api }
95
/**
96
 * BackToTop Vue component
97
 */
98
interface BackToTopComponent {
99
  name: 'BackToTop';
100
  props: {
101
    threshold: {
102
      type: Number;
103
      default: 300;
104
    };
105
  };
106
  data(): {
107
    scrollTop: number | null;
108
  };
109
  computed: {
110
    show(): boolean;
111
  };
112
  methods: {
113
    getScrollTop(): number;
114
    scrollToTop(): void;
115
  };
116
  mounted(): void;
117
}
118

119
/**
120
 * Template interface - SVG-based back-to-top button
121
 */
122
interface BackToTopTemplate {
123
  /** Click handler for scrolling to top */
124
  '@click': 'scrollToTop';
125
  /** Conditional visibility based on show computed property */
126
  'v-if': 'show';
127
  /** CSS class applied to the SVG element */
128
  class: 'go-to-top';
129
  /** Fade transition wrapper */
130
  transition: 'fade';
131
}
132
```
133

134
**Props:**
135
- `threshold`: Number - Scroll position in pixels after which the button becomes visible (default: 300)
136

137
**Data Properties:**
138
- `scrollTop`: Current scroll position in pixels
139

140
**Computed Properties:**
141
- `show`: Boolean indicating whether the button should be visible (based on scroll position vs threshold)
142

143
**Methods:**
144
- `getScrollTop()`: Returns current scroll position from window, document, or body
145
- `scrollToTop()`: Scrolls to top of page with smooth behavior and resets scrollTop to 0
146

147
**Lifecycle Hooks:**
148
- `mounted()`: Sets up initial scroll position and adds debounced scroll event listener to window
149

150
### App Enhancement Function
151

152
Registers the BackToTop component globally in the Vue application.
153

154
```javascript { .api }
155
/**
156
 * VuePress app enhancement function
157
 * @param {Object} context - VuePress app context
158
 * @param {Vue} context.Vue - Vue constructor
159
 */
160
function enhanceApp({ Vue }: { Vue: any }): void;
161
```
162

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

165
## Technical Implementation Details
166

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

174
### Styling
175
- Fixed position at bottom-right corner (2rem from bottom, 2.5rem from right)
176
- SVG arrow icon with hover effects
177
- Color uses VuePress theme's `$accentColor` variable
178
- 2rem width with proper z-index for overlay positioning
179

180
**CSS Classes:**
181
- `.go-to-top`: Main button styling (fixed position, cursor, color, dimensions)
182
- `.go-to-top:hover`: Hover state with lighter accent color
183
- `.fade-enter-active`, `.fade-leave-active`: Transition animation classes (0.3s opacity)
184
- `.fade-enter`, `.fade-leave-to`: Fade animation states (opacity: 0)
185

186
### Dependencies
187
- `@vuepress/types`: TypeScript definitions for VuePress plugin API
188
- `lodash.debounce`: Scroll event throttling
189
- `@vuepress/shared-utils`: Path utilities for file resolution
190

191
## Error Handling
192

193
The plugin is designed to be fault-tolerant:
194
- Graceful fallbacks for scroll position detection across browsers
195
- No error throwing - component will simply not show if there are issues
196
- Automatic cleanup of scroll listeners when component is destroyed
197

198
## Types
199

200
```typescript { .api }
201
// VuePress Plugin Types
202
interface Plugin<T = any, U = any> {
203
  enhanceAppFiles?: string | string[];
204
  globalUIComponents?: string | string[];
205
}
206

207
interface PluginConfig4BackToTop {}
208

209
// Component Props Interface
210
interface BackToTopProps {
211
  threshold?: number;
212
}
213

214
// Vue Component Data Interface
215
interface BackToTopData {
216
  scrollTop: number | null;
217
}
218

219
// App Enhancement Context
220
interface EnhanceAppContext {
221
  Vue: any;
222
}
223
```