@smooth-scrollbar-contrib/vue-test
TypeScript icon, indicating that this package has built-in type declarations

0.0.11 • Public • Published

@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
Vue 2.6
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
Nuxt ≤ 2.15.6 and Vue 2.6

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
Composables

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>
Directive

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

    SSR directives example in Nuxt3
    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 CLI 4 (webpack 4)
    // vue.config.js
    
    module.exports = {
      transpileDependencies: ['@smooth-scrollbar-contrib/vue-wrapper'],
    }
    Vue CLI 3 (webpack 4)
    // 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

License

Package Sidebar

Install

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

Weekly Downloads

1

Version

0.0.11

License

ISC

Unpacked Size

61.5 kB

Total Files

34

Last publish

Collaborators

  • sadeghbarati
  • ehsan_shv
  • dolphin_wood