tailwind-scrollbar

tailwind-scrollbar is a Tailwind CSS plugin that provides styling utilities for scrollbars. It unifies the two competing browser standards into a single API:

1. The scrollbar-width and scrollbar-color properties (used by Firefox and newer Chromium-based browsers).
2. The ::-webkit-scrollbar family of pseudoelements (used by other browsers).

By using this plugin, you can configure scrollbar styles for both standards simultaneously using Tailwind utilities.

When using tailwind-scrollbar, keep the following distinctions in mind:

• Styling vs. Triggering: This plugin only styles existing scrollbars. It does not make scrollbars appear. You must use standard CSS/Tailwind overflow utilities (e.g., overflow-auto, overflow-scroll) to ensure a scrollbar is present before applying styles.
• Unified API vs. Full Customization: The plugin is designed to unify existing browser APIs rather than creating entirely new, fully custom scrollbar elements. It is subject to the inherent limitations of the underlying browser APIs.
• Cross-browser Consistency: While the plugin helps ensure scrollbars match your site's theme across different browsers, it does not guarantee perfect visual replication. Scrollbars will still retain some browser- and OS-specific characteristics.

You can use scrollbar-hover: and scrollbar-active: variants to change the thumb color when the user interacts with it.

Important Requirements:

1. These variants only work on scrollbars styled using pseudoelements (the preferred strategy). Standards-track scrollbars (like default Firefox or Chrome/Edge) handle these states natively.
2. Version Note: If you are using tailwind-scrollbar v3, use the built-in hover: and active: variants instead of scrollbar-hover: and scrollbar-active:.

<div class="scrollbar-hover:scrollbar-thumb-sky-500 scrollbar-active:scrollbar-thumb-sky-400 h-32 scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 overflow-y-scroll">
    <div class="h-64 bg-slate-400"></div>
</div>

Register the plugin in your CSS entry point using the @plugin directive. This allows you to use scrollbar styling utilities throughout your project.

@import 'tailwindcss';

/* ... */

@plugin 'tailwind-scrollbar';

The website can be deployed using different methods depending on your hosting setup:

• Using SSH: Set the USE_SSH environment variable to true.
• Using GitHub Pages: Provide your GitHub username via the GIT_USER environment variable. This will build the site and push it to the gh-pages branch.

Register the plugin in your Tailwind configuration file. Use the @plugin directive for Tailwind CSS v4 (CSS configuration) or the plugins array for Tailwind CSS v3 (JavaScript configuration).

/* Tailwind CSS v4 (New CSS Config) */
@import 'tailwindcss';

@plugin 'tailwind-scrollbar';

/* Tailwind CSS v3 (Legacy JavaScript Config) */
module.exports = {
    // ...
    plugins: [
        // ...
        require('tailwind-scrollbar'),
    ],
};

To generate the static production files, run yarn build. This will create a build directory containing the static content, which can be hosted on any static web hosting service.

$ yarn build

When upgrading to tailwind-scrollbar@^4.0.0, note that while it supports Tailwind CSS v4, the semantics for hover and active states have changed.

In v3, hover:scrollbar-thumb-red-100 applied the style when the element was hovered. In v4, hover: still applies to the element, but if you want to target the scrollbar components specifically, you must use the new scrollbar- prefixed variants.

Install the tailwind-scrollbar package as a development dependency using your preferred package manager.

Compatibility Note: tailwind-scrollbar v4 is only compatible with tailwindcss v4. If you are using tailwindcss v3, you must use tailwind-scrollbar v3.

# npm
npm install --save-dev tailwind-scrollbar

# yarn
yarn add -D tailwind-scrollbar

# pnpm
pnpm add -D tailwind-scrollbar

To work on the website locally, install the dependencies using yarn and then start the development server with yarn start. The development server supports live reloading, so most changes will be reflected in the browser immediately.

$ yarn
$ yarn start