📜 vue-native-scroller

Vue.js wrapper component over browser scroll API.

🌈 The main purpose of the library is just to give you a simple wrapper over browser native scroll API.

The library internally uses scroll method.

✨ Features

• lightweight (~ 2.5kb gzip);
• zero dependency;
• simple API;

Demo

💿 Installation

📦 Via NPM

npm install vue-native-scroller --save

🧶 Via Yarn

yarn add vue-native-scroller

Initialization

As a plugin

It must be called before new Vue().

import Vue from 'vue'
import VueNativeScroller from 'vue-native-scroller'

Vue.use(VueNativeScroller)

As a global component

import Vue from 'vue'
import { VueNativeScroller } from 'vue-native-scroller'

Vue.component('VueNativeScroller', VueNativeScroller)

As a local component

import { VueNativeScroller } from 'vue-native-scroller'

export default {
  name: 'YourAwesomeComponent',
  components: {
    VueNativeScroller,
  },
}

🚀 Usage

Template

Just wrap your items into the <vue-native-scroller> component:

<template>
  <vue-native-scroller>
    <div>foo</div>
    <div>bar</div>
    <div>baz</div>
  </vue-native-scroller>
</template>

🎨 Styles

Then don't forget to include core styles:

SASS:

@import 'vue-native-scroller/src/styles/core.scss';

Or already compiled CSS:

CSS:

@import 'vue-native-scroller/dist/styles/core.css';

Library is shipped with default theme, so if you want to import it, then do the following:

@import 'vue-native-scroller/src/styles/themes/default.scss';

API

⚙️ Props

<vue-native-scroller> accepts some props through which you can customize different aspects of scroll logic.

| Prop | Default | Description | | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------ | | behavior | 'smooth' | Specifies scroll behavior. Possible values are: ['smooth', 'instant', 'auto'] | | align | 'center' | Specifies alignment of the item relatively to the parent. Possible values are: ['left', 'center', 'right'] | | scrollbar | false | Specifies whether or not the scrollbar is visible | | tag | 'div' | Specifies the tag of the container |

Example of props passing

<vue-native-scroller
  behavior="instant"
  align="left"
  tag="section"
  scrollbar
></vue-native-scroller>

🎛 Methods

<vue-native-scroller> provides you with several methods you can use to scroll left, right or to certain item.

ℹ️ options object in the bellow methods, is the object through which you can specify custom behavior and alignment of the scroll action. It can contain 2 properties with keys align and behavior. align value should be one of the following values ['left', 'center', 'right'], and behavior: ['smooth', 'instant', 'auto']. If one of the keys is not specified, value passed by props is used (if value is not passed, default value is used).

| Method | Description | | ------------------------------------------------ | ---------------------------------------- | | scrollToIndex(index: number, options?: object) | Scrolls to the item with specified index | | scrollLeft(options?: object) | Scrolls left | | scrollRight(options?: object) | Scrolls right |

Example of methods usage

<template>
  <vue-native-scroller ref="scroller"></vue-native-scroller>
</template>

// ...
export default {
  // ...
  name: 'YourAwesomeComponent',
  methods: {
    method() {
      const { scroller } = this.$refs

      scroller.scrollToIndex(1)
      scroller.scrollLeft({ align: 'center' })
      scroller.scrollRight({ align: 'right', behavior: 'instant' })
    },
  },
  // ...
}
// ...

🕳️ Slots

<vue-native-scroller> provides you with some scopedSlots you can use to fit your needs.

| Slot | Scope | Description | | --------- | ----------------- | ------------------------------------------- | | prepend | { scrollLeft } | Slot that is prepended to the list of items | | append | { scrollRight } | Slot that is appended to the list of items |

Example of possible usage of scopedSlots

<template>
  <vue-native-scroller>
    <template v-slot:prepend="{ scrollLeft }">
      <button type="button" @click="scrollLeft">Scroll left</button>
    </template>
    <div>foo</div>
    <div>bar</div>
    <div>baz</div>
    <template v-slot:append="{ scrollRight }">
      <button type="button" @click="scrollRight">Scroll right</button>
    </template>
  </vue-native-scroller>
</template>

💉 Tests

Unit

Jest and VueTestUtils is used for unit tests.

You can run unit tests by running next command:

npm run test:unit

Powered by

• Rollup (and plugins);
• SASS and node-sass;
• PostCSS;
• Autoprefixer;
• VueTestUtils;
• Jest.

🔒 License

MIT