@smooth-scrollbar-contrib/vue-wrapper

Features

• 💚 Works with Vue 3.2, 2.7, 2.6
• 🧱 Component
• ⚗️ Composable
• 📜 Directive (no SSR)
• 🍃 Tree shakeable

Installation

Since smooth-scrollbar is an external dependency you have to install it individually

Warning: This package uses composition-api setup syntax, script setup is recommended

Vue 3.2, 2.7, Nuxt 3 and Nuxt Bridge 2.16+

npm i smooth-scrollbar @smooth-scrollbar-contrib/vue-wrapper

npm i @vue/composition-api smooth-scrollbar @smooth-scrollbar-contrib/vue-wrapper

# bring `<script setup>` to Vue 2.
npm i -D unplugin-vue2-script-setup

# if you using Volar
npm i -D @vue/runtime-dom

Older version of Nuxt that uses Vue 2.6

npm i smooth-scrollbar @smooth-scrollbar-contrib/vue-wrapper

# automatically configured using unplugin-vue2-script-setup
npm i -D @nuxtjs/composition-api

# if you using Volar
npm i -D @vue/runtime-dom

Usage

Component

<template>
  <Scrollbar ref="scrollbarRef" as="div" :scrollbar-options="scrollbarOptions" @mounted="">
    <div> <!-- it's recommended to use a wrapper for your content -->
      Component
    </div>
  </Scrollbar>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { Scrollbar, type ScrollbarOptions } from "@smooth-scrollbar-contrib/vue-wrapper"

const scrollbarRef = ref<InstanceType<typeof Scrollbar> | null>(null)

const scrollbarOptions: ScrollbarOptions = {
  delegateTo: typeof document !== 'undefined' ? document : null, // if you are using ssr
  damping: 0.2
}
</script>

With component you have these features:

• Exposed scrollbar, access the scrollbar instance at the place you used the Component, with Ref on Component
• Provide / Inject, access scrollbar instance inside child components with useScrollbarInject composable
• Watch target changes like v-if, destroy and re-init automatically

Props

| Name | Description | Default | Type | | ----------- | ----------- | ----------- | ----------- | | as | The element that the component should be rendered as | div | string | scrollbar-options | Options for Scrollbar, please refer to smooth-scrollbar documentation | undefined | ScrollbarOptions |

Emit

| Name | Description | Payload | Type | | ----------- | ----------- | ----------- | ----------- | | mounted | Scrollbar mounted | { target, scrollbar } | MountedEmitPayload |

Note: If you need other lifecycle methods you can use Vue vnode lifecycle events/hooks for beforeMount and beforeUnmount / beforeDestroy

Vue3: @vue:beforeMount / @vnode-before-mount and @vue:beforeUnmount / @vnode-before-unmount

Vue2: @hook:beforeMount and @hook:beforeDestroy

Expose

| Name | Description | Type | | ---------- | ------------------- | ------ | | scrollbar | smooth-scrollbar instance | object |

useScrollbar

Create smooth-scrollbar with composable

<template>
  <div ref="target">
    <div> <!-- it's recommended to use a wrapper for your content -->
      Composable
    </div>
  </div>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { useScrollbar } from "@smooth-scrollbar-contrib/vue-wrapper"

const target = ref<HTMLElement | null>(null)

const scrollbar = useScrollbar(target, {
  delegateTo: typeof document !== 'undefined' ? document : null, // if you are using ssr
  damping: 0.2
})
</script>

useScrollbarInject

Inject smooth-scrollbar instance to component's descendants

<script lang="ts" setup>
import { useScrollbarInject } from "@smooth-scrollbar-contrib/vue-wrapper"

const scrollbar = useScrollbarInject()
</script>

Vue directive for smooth-scrollbar with CustomEvents

Warning: Custom directive intended to use only on client-side

<template>
  <div v-scrollbar="{
    damping: 0.2
  }"
  @scrollbar-mounted="mountedFn"
  @scrollbar-unmounted="unmountedFn"
  >
    <div> <!-- it's recommended to use a wrapper for your content -->
      Directive
    </div>
  </div>
</template>

<script lang="ts" setup>
import type SmoothScrollbar from 'smooth-scrollbar'
import { vScrollbar } from "@smooth-scrollbar-contrib/vue-wrapper"

function mountedFn(event: CustomEvent<SmoothScrollbar>) {
  console.log(event.detail) // smooth-scrollbar instance
}

function unmountedFn(event: CustomEvent<HTMLElement>) {
  console.log(event.detail) // smooth-scrollbar element
}
</script>

CustomEvents

| Name | Description | Callback (detail) | | ----------- | ----------- | ----------- | | scrollbar-mounted | fired when the DOM element is inserted and the library is loaded on it | smooth-scrollbar instance | | scrollbar-unmounted | fired when the DOM element is unbound and the library is unloaded. | smooth-scrollbar element |

Limitation

• Vue ≤ 2.6 has partial TypeScript support in templates, also @vue/composition-api reached End of Life, so it's better to upgrade your app to 2.7 or 3.2
• Volar or Vetur? Vue team recommends using Volar, however, you must set vueCompilerOptions in your tsconfig.json file

{
  "compilerOptions": {
    // ...
  },
  "vueCompilerOptions": {
    "target": 2.7,
    // "target": 2, // For Vue version <= 2.6.14
  }
}

• Custom directive intended to use only on client-side, though it can configure to use in SSR app

  import { defineNuxtPlugin } from '#app';
  import { vScrollbar } from '@smooth-scrollbar-contrib/vue-wrapper'
  
  export default defineNuxtPlugin((app) => {
    app.vueApp.directive('vScrollbar', {
      ...vScrollbar,
      getSSRProps(binding, vnode) {
        return {};
      }
    });
  })

• unbuild (The package that builds this project) uses ES2020 as compiler target by default, If you are using older tools like Vue CLI ≤ 4 and use import instead of require you have to take care about backward-compatible JavaScript code

  // vue.config.js
  
  module.exports = {
    transpileDependencies: ['@smooth-scrollbar-contrib/vue-wrapper'],
  }

  // vue.config.js
  
  module.exports = {
    transpileDependencies: ['@smooth-scrollbar-contrib/vue-wrapper'],
    chainWebpack(config) {
      // Getting webpack to recognize the `.mjs` file
      config.module
        .rule('mjs')
        .include.add(/node_modules/)
        .type('javascript/auto')
        .end()
    },
  }

Best Practice

• Use wrapper element for your content or slot inside Scrollbar component
• Use shallowRef for Template Refs
• Use plain object over ref object for Scrollbar options, cause smooth-scrollbar options are read-only after Scrollbar is initialized
• Use v-memo, If you are using Scrollbar component inside your custom component (that has many props or states) to skip re-render, when it's not needed
• Use local registration instead of global registration

CLI

This package is using simple postinstall script and cli in order to get the right Vue build for user

Manually Switch Versions

To explicitly switch the redirecting version, you can use these commands in your project's root.

npx smooth-scrollbar-vue-switch 2.6
# or
npx smooth-scrollbar-vue-switch 2.7
# or
npx smooth-scrollbar-vue-switch 3

Auto Fix

If the postinstall hook doesn't get triggered or you have updated the Vue version, try to run the following command to resolve the redirecting.

npx smooth-scrollbar-vue-fix

Credits

• vue-demi
• smooth-vuebar
• json-editor-vue

License