Vue Scroller

2.2.4 · maintenance · verified Tue Apr 21

Vue Scroller is a Vue 2 component designed to provide smooth scrolling capabilities, including features like pull-to-refresh and infinite loading. It served as a foundational component for the Vonic UI framework. The package is currently at version 2.2.4 on npm, with the last update approximately four years ago. This indicates that it is tailored specifically for Vue 2 environments and is not actively maintained for compatibility with Vue 3 or newer ecosystems. Its primary differentiators lie in its straightforward API for implementing common mobile-like scrolling patterns within Vue 2 applications. Due to its age, new projects are generally advised to seek more modern, actively maintained alternatives, especially if targeting Vue 3.

Common errors

```
[Vue warn]: Unknown custom element: <scroller> - did you register the component correctly?
```
cause The `Vue.use(VueScroller)` plugin installation was skipped or placed after the Vue instance creation.

fix Ensure `import Vue from 'vue'; import VueScroller from 'vue-scroller'; Vue.use(VueScroller);` runs before `new Vue({...})` to globally register the `<scroller>` component.
```
TypeError: Cannot read properties of undefined (reading 'refresh')
```
cause The `on-refresh` or `on-infinite` callback method is not defined in the Vue component's `methods` option.

fix Define the `refresh` and `infinite` methods in your Vue component's `methods` object, ensuring they accept `done` as an argument and call `done()` when the operation is complete.
```
Error: Scroller requires a child element to scroll.
```
cause The `<scroller>` component must have content inside its default slot to enable scrolling.

fix Place your scrollable content directly inside the `<scroller>` tags, e.g., `<scroller><div class="content">...</div></scroller>`.

Warnings

breaking Vue Scroller is designed for Vue 2.x and is not compatible with Vue 3.x without significant modifications or community-maintained forks. Attempting to use it directly in a Vue 3 project will result in errors.
Fix: For Vue 3 projects, consider using more modern alternatives like 'vue-virtual-scroller', 'vue-scrollto', or implementing custom solutions with Vue's reactivity system. If migrating a Vue 2 project, plan to replace this component.
deprecated The `resize()` instance method for the scroller component is deprecated. The scroller content is designed to resize itself automatically.
Fix: Remove any manual calls to `this.$refs.scroller.resize()`. Rely on the component's automatic resizing behavior or trigger updates via Vue's reactivity system if content changes dynamically in ways not automatically detected.
gotcha The default `refreshText` and `noDataText` attributes are set to Chinese characters ('下拉刷新' and '没有更多数据' respectively).
Fix: Always explicitly set `refreshText` and `noDataText` attributes to your desired language strings, e.g., `:refresh-text="'Pull to refresh'"` and `:no-data-text="'No more data'"`.
gotcha The package has not been updated in over four years (as of 2026), indicating it is no longer actively maintained. This means no new features, bug fixes, or security patches will be released.
Fix: For new projects, prefer actively maintained scrolling libraries. For existing projects using `vue-scroller`, be aware of potential unaddressed bugs or security vulnerabilities and consider migrating to a newer solution in the long term.

Install

npm install vue-scroller npm
yarn add vue-scroller yarn
pnpm add vue-scroller pnpm

Imports

VueScroller
wrong:
```
import { VueScroller } from 'vue-scroller';
```
correct:
```
import VueScroller from 'vue-scroller';
```
VueScroller is a default export. Ensure you import it as such.
plugin installation
wrong:
```
new Vue({
  components: { VueScroller }
});
```
correct:
```
import Vue from 'vue';
import VueScroller from 'vue-scroller';

Vue.use(VueScroller);
```
Vue Scroller registers itself globally as a component named 'scroller' when Vue.use() is called.
CommonJS (older Node/builds)
wrong:
```
const VueScroller = require('vue-scroller');
```
correct:
```
const VueScroller = require('vue-scroller').default;
```
For CommonJS environments, the default export needs to be explicitly accessed after requiring the module.

Quickstart

Demonstrates basic setup, pull-to-refresh, and infinite loading functionality within a Vue 2 application using a global component registration.

import Vue from 'vue';
import VueScroller from 'vue-scroller';

Vue.use(VueScroller);

new Vue({
  el: '#app',
  template: `
    <div style="height: 300px; border: 1px solid #ccc;">
      <scroller 
        :on-refresh="refresh" 
        :on-infinite="infinite"
        height="100%"
      >
        <p v-for="item in items" :key="item">{{ item }}</p>
      </scroller>
    </div>
  `,
  data: {
    items: []
  },
  methods: {
    refresh(done) {
      console.log('Refreshing data...');
      setTimeout(() => {
        this.items = Array.from({ length: 20 }, (_, i) => `Refreshed Item ${i + 1}`);
        done(); // Signal that refresh is complete
      }, 1500);
    },
    infinite(done) {
      console.log('Loading more data...');
      setTimeout(() => {
        const newItems = Array.from({ length: 10 }, (_, i) => `Loaded Item ${this.items.length + i + 1}`);
        this.items.push(...newItems);
        if (this.items.length >= 50) {
          done(true); // Signal no more data
        } else {
          done(); // Signal loading is complete
        }
      }, 1000);
    }
  },
  mounted() {
    this.refresh(() => {}); // Initial load
  }
});

view raw JSON →