vue3-smooth-scrollbar

vue3-smooth-scrollbar

Based on vue-smooth-scrollbar

Requirements

• Vue 3.5+
• smooth-scrollbar 8.8+

Installation

npm install vue3-smooth-scrollbar smooth-scrollbar
# or
bun add vue3-smooth-scrollbar smooth-scrollbar

Usage

Custom main scrollbar

App.vue

<template>
  <Scrollbar>
    <!-- content -->
  </Scrollbar>
</template>

<script setup lang="ts">
import Scrollbar from "vue3-smooth-scrollbar"
import "vue3-smooth-scrollbar/styles.css"
</script>

Add smooth-scrollbar-body to <body> and smooth-scrollbar-root to the element that wraps the scrollbar (for example #app):

<body class="smooth-scrollbar-body">
  <div id="app" class="smooth-scrollbar-root"></div>
</body>

Or apply the equivalent rules in your own CSS:

body {
  margin: 0;
  height: 100%;
  overflow: hidden;
}

#app {
  height: 100vh;
  width: 100%;
  overflow: auto;
}

smooth-scrollbar still injects track and thumb styles when the component mounts. You only need a custom setup if you call SmoothScrollbar.detachStyle() from smooth-scrollbar.

Development

This project uses Bun for package management.

Project setup

bun install

Dev server with hot reload

bun run dev

Build library for production

bun run build

Lint

bun run lint

Typecheck

bun run typecheck

Releasing

Releases are managed with Changesets.

1. After your changes are merged, add a changeset:

   bun run changeset
   

   Choose the semver bump (patch, minor, or major) and write a short summary.

2. Commit the generated file in .changeset/ and open a PR.

3. When changesets land on master, GitHub Actions opens a Version Packages PR that bumps package.json and updates CHANGELOG.md.

4. Merging that PR triggers the release workflow, which builds and publishes to npm.

Required repository secrets:

• NPM_TOKEN — npm Automation access token with publish rights for this package

GITHUB_TOKEN is provided automatically for release PRs and GitHub releases.

npm 2FA and CI

If the Release workflow fails with EOTP / "requires a one-time password", the npm account has 2FA enabled and the token is not allowed to publish from CI.

Create a new token at npm → Access Tokens:

1. Classic token → type Automation (bypasses 2FA for CI), or
2. Granular token → allow Read and write for vue3-smooth-scrollbar

Then update the GitHub secret:

gh secret set NPM_TOKEN --repo orafal-dev/vue3-smooth-scrollbar

Re-run the failed Release workflow after updating the secret.