tailwind-scrollbar - npm Package Compare versions

Comparing version 3.0.5 to 3.1.0-rc.0

package.json

 {
   "name": "tailwind-scrollbar",
-  "version": "3.0.5",
+  "version": "3.1.0-rc.0",
   "description": "Tailwind plugin for styling scrollbars",
@@ -5,0 +5,0 @@ "author": "Graham Still <[e-mail]>",

README.md

@@ -6,86 +6,36 @@ # Scrollbar Plugin for Tailwind CSS
 
-Adds styling utilities for scrollbars in Firefox and webkit-based browsers.
+`tailwind-scrollbar` is a plugin for [Tailwind CSS](https://tailwindcss.com) that adds styling utilities for scrollbars with cross-browser support.
 
+## Motivation
+There are currently two competing standards for styling scrollbars amongst browsers: the [scrollbar-width](https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-width) and [scrollbar-color](https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-color) properties used by Firefox and newer Chromium-based browsers, and the [::-webkit-scrollbar](https://developer.mozilla.org/en-US/docs/Web/CSS/::-webkit-scrollbar) family of pseudoelements used by everything else. This plugin defines a single API for configuring both standards at once from within Tailwind.
+
 ## Installation
 
+1. Add the package to your project
 ```bash
+# npm
+npm install --save-dev tailwind-scrollbar
+# yarn
 yarn add -D tailwind-scrollbar
+# pnpm
+pnpm add -D tailwind-scrollbar
 ```
-or
-```bash
-npm install --save-dev tailwind-scrollbar
-```
 
-Add it to the plugins array of your Tailwind config.
+2. Add it to the plugins array of your Tailwind config
 
-```js
-plugins: [
+```javascript
+module.exports = {
     // ...
-    require('tailwind-scrollbar'),
-],
+    plugins: [
+        // ...
+        require('tailwind-scrollbar'),
+    ],
+};
 ```
 
 ## Usage
+See the [documentation](https://adoxography.github.io/tailwind-scrollbar/examples).
 
-**NB:** This plugin *styles* scrollbars; it does not force them to appear. Use typical CSS techniques to force content to overflow and trigger a scrollbar.
-
-For every element that you want to style, add either the `scrollbar` or `scrollbar-thin` class. You may then add any `scrollbar-track-{color}`, `scrollbar-thumb-{color}` or `hover:scrollbar-thumb-{color}` classes you like. (Note that `hover:scrollbar-thumb-{color}` classes only have effects in webkit-based browsers.)
-
-If you're using both vertical and horizontal scrollbars, you may notice a white square show up. You can change its colour with the `scrollbar-corner-{color}` utility.
-
-Here's a minimal example (keeping in mind that the `h-32` and `h-64` classes are just there to force the scrollbar to appear):
-
-```html
-<div class="h-32 scrollbar scrollbar-thumb-gray-900 scrollbar-track-gray-100">
-    <div class="h-64"></div>
-</div>
-```
-
-A live version of this demo [can be found here](https://tailwind-scrollbar-example.adoxography.repl.co/).
-
-## Configuration
-
-This plugin is capable of adding utilties for creating rounded scrollbars by referencing your configured [border radius](https://tailwindcss.com/docs/border-radius#customizing) settings. However, as they are only supported in chromium-based browsers, their usage is inadvisable in cross-browser applications. To enable rounded scrollbar utilities, pass `nocompatible: true` to the plugin during its declaration; e.g.:
-
-```js
-plugins: [
-    // ...
-    require('tailwind-scrollbar')({ nocompatible: true }),
-],
-```
-
-This will add utilities such as `scrollbar-thumb-rounded` or `scrollbar-thumb-rounded-md`.
-
-## Complete list of utilities
-All utilities are compatible with variants, unless otherwise specified.
-
-### Width utilities
-These utilities initialize scrollbar styling. You always need one of them, even if you're using custom widths. (See below.)
-
-| Utility     | Effect | Notes |
-|-------------|--------|-------|
-| `scrollbar` | Enables custom scrollbar styling, using the default width | On Firefox, this is `scrollbar-width: auto`, which is `16px`. Chrome is hard coded to `16px` for consistency. |
-| `scrollbar-thin` | Enables custom scrollbar styling, using the thin width | On Firefox, this is `scrollbar-width: thin`, which is `8px`. Chrome is hard coded to `8px` for consistency. |
-| `scrollbar-none` | Hides the scrollbar completely | Because of browser quirks, this cannot be used to hide an existing styled scrollbar - i.e. `scrollbar hover:scrollbar-none` will not work. |
-
-### Colour utilities
-All of the asterisks can be replaced [with any tailwind colour](https://tailwindcss.com/docs/customizing-colors#using-custom-colors), including [arbitrary values](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values) and [opacity modifiers](https://tailwindcss.com/docs/background-color#changing-the-opacity). With the exception of the width utilities, all utilities are inherited by child elements.
-
-| Utility     | Effect | Notes |
-|-------------|--------|-------|
-| `scrollbar-thumb-*` | Sets the colour of the scrollbar thumb | |
-| `scrollbar-track-*` | Sets the colour of the scrollbar track | |
-| `scrollbar-corner-*` | Sets the colour of the scrollbar corner | The corner will only appear if you have both vertical and horizontal scrollbars. |
-
-### Nocompatible utilities
-These styles are only available in `nocompatible` mode. They won't have any effect in Firefox.
-
-| Utility     | Effect | Notes |
-|-------------|--------|-------|
-| `scrollbar-w-*` | Sets the width of vertical scrollbars | The asterisk can be replaced with any Tailwind [width setting](https://tailwindcss.com/docs/width), including arbitrary values. Only applies to scrollbars styled with `scrollbar` (not `scrollbar-thin`). |
-| `scrollbar-h-*` | Sets the height of horizontal scrollbars | The asterisk can be replaced with any Tailwind [height setting](https://tailwindcss.com/docs/height), including arbitrary values. Only applies to scrollbars styled with `scrollbar` (not `scrollbar-thin`). |
-| `scrollbar-rounded-*` | Rounds a scrollbar thumb's corners | The asterisk can be replaced with any Tailwind [rounded setting](https://tailwindcss.com/docs/border-radius#using-custom-values), including arbitrary values. |
-
 ## License
 
 This project is licensed under the [MIT License](/LICENSE).

src/index.js

 const plugin = require('tailwindcss/plugin');
 const {
-  BASE_STYLES,
-  SCROLLBAR_SIZE_UTILITIES,
+  addBaseStyles,
+  addBaseSizeUtilities,
   addColorUtilities,
@@ -12,4 +12,12 @@ addRoundedUtilities,
 module.exports = plugin.withOptions((options = {}) => tailwind => {
-  tailwind.addBase(BASE_STYLES);
-  tailwind.addUtilities(SCROLLBAR_SIZE_UTILITIES);
+  let preferredStrategy = options.preferredStrategy ?? 'standard';
+
+  if (preferredStrategy !== 'standard' && preferredStrategy !== 'pseudoelements') {
+    // eslint-disable-next-line no-console
+    console.warn('WARNING: tailwind-scrollbar preferredStrategy should be \'standard\' or \'pseudoelements\'');
+    preferredStrategy = 'standard';
+  }
+
+  addBaseStyles(tailwind, preferredStrategy);
+  addBaseSizeUtilities(tailwind, preferredStrategy);
   addColorUtilities(tailwind);
@@ -16,0 +24,0 @@ addVariantOverrides(tailwind);

src/utilities.d.ts

 /**
  * Base resets to make the plugin's utilities work
+ *
+ * @param {typedefs.TailwindPlugin} tailwind - Tailwind's plugin object
+ * @param {'standard' | 'peseudoelements'} preferredStrategy - The preferred
+ *    scrollbar styling strategy: standards track or pseudoelements
  */
-export const BASE_STYLES: {
-    '*': {
-        'scrollbar-color': string;
-        'scrollbar-width': string;
-    };
-};
+export function addBaseStyles({ addBase }: typedefs.TailwindPlugin, preferredStrategy: 'standard' | 'peseudoelements'): void;
 /**
- * Utilities for initializing a custom styled scrollbar, which implicitly set
- * the scrollbar's size
+ * @param {typedefs.TailwindPlugin} tailwind - Tailwind's plugin object
+ * @param {'standard' | 'peseudoelements'} preferredStrategy - The preferred
+ *    scrollbar styling strategy: standards track or pseudoelements
  */
-export const SCROLLBAR_SIZE_UTILITIES: {
-    '.scrollbar': any;
-    '.scrollbar-thin': any;
-    '.scrollbar-none': {
-        'scrollbar-width': string;
-        '&::-webkit-scrollbar': {
-            display: string;
-        };
-    };
-};
+export function addBaseSizeUtilities({ addUtilities }: typedefs.TailwindPlugin, preferredStrategy: 'standard' | 'peseudoelements'): void;
 /**
@@ -25,0 +16,0 @@ * Adds scrollbar-COMPONENT-COLOR utilities for every scrollbar component.

src/utilities.js

@@ -14,18 +14,40 @@ const flattenColorPaletteImport = require('tailwindcss/lib/util/flattenColorPalette');
 /**
- * Base resets to make the plugin's utilities work
+ * @param {Record<never, unknown>} properties - The properties to assign
+ * @param {boolean} preferPseudoElements - If true, only browsers that cannot
+ *    use pseudoelements will specify scrollbar properties
+ * @returns {Record<string, unknown>} - The generated CSS rules
  */
-const BASE_STYLES = {
-  '*': {
-    'scrollbar-color': 'initial',
-    'scrollbar-width': 'initial'
+const scrollbarProperties = (properties, preferPseudoElements) => {
+  if (preferPseudoElements) {
+    return {
+      '@supports (-moz-appearance:none)': properties
+    };
   }
+
+  return properties;
 };
 
 /**
- * Tells an element what to do with --scrollbar-track and --scrollbar-thumb
- * variables
+ * Base resets to make the plugin's utilities work
+ *
+ * @param {typedefs.TailwindPlugin} tailwind - Tailwind's plugin object
+ * @param {'standard' | 'peseudoelements'} preferredStrategy - The preferred
+ *    scrollbar styling strategy: standards track or pseudoelements
  */
-const SCROLLBAR_SIZE_BASE = {
-  'scrollbar-color': 'var(--scrollbar-thumb, initial) var(--scrollbar-track, initial)',
+const addBaseStyles = ({ addBase }, preferredStrategy) => {
+  addBase({
+    '*': scrollbarProperties({
+      'scrollbar-color': 'initial',
+      'scrollbar-width': 'initial'
+    }, preferredStrategy === 'pseudoelements')
+  });
+};
 
+/**
+ * Generates utilties that tell an element what to do with
+ * --scrollbar-track and --scrollbar-thumb custom properties
+ *
+ * @returns {Record<string, unknown>} - The generated CSS
+ */
+const generateBaseUtilities = () => ({
   ...Object.fromEntries(COMPONENTS.map(component => {
@@ -47,3 +69,3 @@ const base = `&::-webkit-scrollbar-${component}`;
   }).flat())
-};
+});
 
@@ -53,7 +75,15 @@ /**
  * the scrollbar's size
+ *
+ * @param {object} options - Options
+ * @param {boolean} options.preferPseudoElements - If true, only browsers that
+ *    cannot use pseudoelements will specify scrollbar-width
+ * @returns {Record<string, unknown>} - Base size utilities for scrollbars
  */
-const SCROLLBAR_SIZE_UTILITIES = {
+const generateScrollbarSizeUtilities = ({ preferPseudoElements }) => ({
   '.scrollbar': {
-    ...SCROLLBAR_SIZE_BASE,
-    'scrollbar-width': 'auto',
+    ...generateBaseUtilities(),
+    ...scrollbarProperties({
+      'scrollbar-width': 'auto',
+      'scrollbar-color': 'var(--scrollbar-thumb, initial) var(--scrollbar-track, initial)'
+    }, preferPseudoElements),
 
@@ -68,4 +98,7 @@ '&::-webkit-scrollbar': {
   '.scrollbar-thin': {
-    ...SCROLLBAR_SIZE_BASE,
-    'scrollbar-width': 'thin',
+    ...generateBaseUtilities(),
+    ...scrollbarProperties({
+      'scrollbar-width': 'thin',
+      'scrollbar-color': 'var(--scrollbar-thumb, initial) var(--scrollbar-track, initial)'
+    }, preferPseudoElements),
 
@@ -80,3 +113,5 @@ '&::-webkit-scrollbar': {
   '.scrollbar-none': {
-    'scrollbar-width': 'none',
+    ...scrollbarProperties({
+      'scrollbar-width': 'none'
+    }, preferPseudoElements),
 
@@ -87,3 +122,3 @@ '&::-webkit-scrollbar': {
   }
-};
+});
 
@@ -141,2 +176,13 @@ /**
 /**
+ * @param {typedefs.TailwindPlugin} tailwind - Tailwind's plugin object
+ * @param {'standard' | 'peseudoelements'} preferredStrategy - The preferred
+ *    scrollbar styling strategy: standards track or pseudoelements
+ */
+const addBaseSizeUtilities = ({ addUtilities }, preferredStrategy) => {
+  addUtilities(generateScrollbarSizeUtilities({
+    preferPseudoElements: preferredStrategy === 'pseudoelements'
+  }));
+};
+
+/**
  * Adds scrollbar-w-* and scrollbar-h-* utilities
@@ -159,4 +205,4 @@ *
 module.exports = {
-  BASE_STYLES,
-  SCROLLBAR_SIZE_UTILITIES,
+  addBaseStyles,
+  addBaseSizeUtilities,
   addColorUtilities,
@@ -163,0 +209,0 @@ addRoundedUtilities,

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Lines of code

419

increased by10.85%

Worsened metrics

Total package byte prevSize

18024

decreased by-4.53%

Number of low quality alerts

1

increased byInfinity%

Number of lines in readme file

41

decreased by-54.95%

No dependency changes