Vue Perfect Scrollbar (Vue 2)

0.2.1 · abandoned · verified Sun Apr 19

vue-perfect-scrollbar is a Vue.js 2 wrapper component for the Perfect Scrollbar library, designed to provide custom, cross-browser scrollbars that mimic native scrolling behavior but offer enhanced styling capabilities. The current version, 0.2.1, was last published 7 years ago, indicating that this specific package is abandoned and no longer actively maintained. While it aimed to simplify the integration of perfect-scrollbar into Vue 2 applications, users looking for modern Vue compatibility (Vue 3) or ongoing maintenance should seek alternative, actively developed wrappers like `vue3-perfect-scrollbar`. This package does not have a regular release cadence due to its abandoned status.

Common errors

```
[Vue warn]: Unknown custom element: <VuePerfectScrollbar>
```
cause The VuePerfectScrollbar component was not correctly registered with Vue, or there's a typo in the component name.

fix Ensure `import VuePerfectScrollbar from 'vue-perfect-scrollbar'` is present in your script, and the component is registered in `components: { VuePerfectScrollbar }` within your Vue component definition.
```
Scrollbars are not visible or do not function correctly.
```
cause Missing `perfect-scrollbar` CSS import or the container element does not have `position: relative`.

fix 1. Add `import 'perfect-scrollbar/css/perfect-scrollbar.css'` to your project. 2. Ensure the CSS for the scrollable area includes `position: relative;`.
```
VuePerfectScrollbar does not update after content changes (e.g., new items added to a list).
```
cause Perfect Scrollbar often requires manual `update()` calls when its content or container dimensions change, and this wrapper might not automatically detect all changes.

fix After content changes that affect scrollable size, you may need to manually trigger an update on the Perfect Scrollbar instance. This typically involves accessing the underlying Perfect Scrollbar instance via a Vue ref and calling its `update()` method, though the exact access path can vary (e.g., `this.$refs.myScrollbar.$children[0].update()`).

Warnings

breaking This `vue-perfect-scrollbar` package is abandoned and has not been updated in over 7 years. It is designed for Vue 2 and is incompatible with Vue 3. Using it in modern Vue projects will lead to significant compatibility issues and a lack of ongoing support or security patches.
Fix: For Vue 3 projects, consider using actively maintained alternatives like `vue3-perfect-scrollbar`. For Vue 2, proceed with caution, acknowledging the lack of updates.
gotcha The underlying `perfect-scrollbar` library and its CSS must be installed and imported separately. This wrapper component does not bundle the core perfect-scrollbar styles, leading to non-functional scrollbars if the CSS is missing.
Fix: Ensure you `npm install perfect-scrollbar` and `import 'perfect-scrollbar/css/perfect-scrollbar.css'` in your main application file or component styles.
gotcha For `perfect-scrollbar` to function correctly, the container element on which `vue-perfect-scrollbar` is applied (or its direct parent) must have `position: relative` CSS property. Failing to set this will result in scrollbars not appearing or behaving erratically.
Fix: Add `position: relative;` to the CSS class of the element wrapping `vue-perfect-scrollbar`, as shown in the quickstart example (e.g., `.scroll-area { position: relative; }`).
deprecated Older versions (prior to 0.0.14) had 'wrong method names for init and uninit', which could cause issues with programmatic control or component lifecycle management. While fixed, this indicates potential instability in early releases.
Fix: Always use version 0.0.14 or newer. Review any manual calls to `init()` or `uninit()` methods if upgrading from very old versions.

Install

npm install vue-perfect-scrollbar npm
yarn add vue-perfect-scrollbar yarn
pnpm add vue-perfect-scrollbar pnpm

Imports

VuePerfectScrollbar
wrong:
```
const VuePerfectScrollbar = require('vue-perfect-scrollbar')
```
correct:
```
import VuePerfectScrollbar from 'vue-perfect-scrollbar'
```
Standard ES Module import for a Vue component. Ensure Vue is configured to handle .vue file imports. This package is for Vue 2.
VuePerfectScrollbar (Webpack/Older Bundlers)
wrong:
```
import { VuePerfectScrollbar } from 'vue-perfect-scrollbar'
```
correct:
```
import VuePerfectScrollbar from 'vue-perfect-scrollbar/index.vue'
```
Some older Webpack or specific build configurations might require importing the .vue file directly. The default export is the component.
CSS Styles
wrong:
```
import 'vue-perfect-scrollbar/dist/perfect-scrollbar.css'
```
correct:
```
import 'perfect-scrollbar/css/perfect-scrollbar.css'
```
The core `perfect-scrollbar` CSS needs to be imported separately. This package does not bundle or re-export the styles.

Quickstart

This quickstart demonstrates how to integrate `vue-perfect-scrollbar` into a Vue 2 application, showing component registration, prop binding for settings, event handling, and essential CSS for correct rendering. It includes a scrollable content area to visualize the custom scrollbar.

<template>
  <VuePerfectScrollbar class="scroll-area" :settings="settings" @ps-scroll-y="scrollHandle">
    <div style="height: 1000px; width: 100%; background: #f0f0f0; padding: 20px;">
      <h1>Scrollable Content</h1>
      <p>This is some long content to demonstrate the scrollbar functionality.</p>
      <p>Scroll down to see more...</p>
      <p v-for="n in 50" :key="n">Line {{ n }} of many.</p>
    </div>
  </VuePerfectScrollbar>
</template>

<script>
import VuePerfectScrollbar from 'vue-perfect-scrollbar'
import 'perfect-scrollbar/css/perfect-scrollbar.css' // Don't forget to import the CSS

export default {
  components: {
    VuePerfectScrollbar
  },
  name: 'App',
  data() {
    return {
      settings: {
        maxScrollbarLength: 60,
        wheelSpeed: 0.5
      }
    }
  },
  methods: {
    scrollHandle(evt) {
      console.log('Scroll Y event:', evt)
    },
    // Example of manually updating the scrollbar
    updateScrollbar() {
      if (this.$refs.scrollbar) {
        // Assuming you add a ref='scrollbar' to VuePerfectScrollbar component
        // this.$refs.scrollbar.$children[0].update(); // Accessing underlying PerfectScrollbar instance
        console.warn('Manual update method might vary based on the Perfect Scrollbar version and wrapper implementation.')
      }
    }
  },
  mounted() {
    // Simulate content change after a delay to show update necessity
    // setTimeout(() => {
    //   // Add more content dynamically
    //   // this.$nextTick(() => this.updateScrollbar());
    // }, 2000);
  }
}
</script>
<style lang="scss">
.scroll-area {
  position: relative; /* Crucial for perfect-scrollbar to work correctly */
  margin: auto;
  width: 400px;
  height: 300px;
  border: 1px solid #ccc;
}
</style>

view raw JSON →