tessl/npm-tailwind-scrollbar

Tailwind plugin for styling scrollbars with cross-browser support

—

Pending

Overview

Eval results

Files

Advanced Utilities

Name: tessl/npm-tailwind-scrollbar
Author: tessl

Size and border radius utilities available in nocompatible mode for fine-grained control.

Capabilities

Size Utilities

Custom width and height utilities for scrollbars, available when nocompatible: true is set in plugin options.

/**
 * Scrollbar width utilities - sets custom scrollbar width
 * Available when nocompatible: true
 */
.scrollbar-w-{size} {
  --scrollbar-width: {size-value};
}

/**
 * Scrollbar height utilities - sets custom scrollbar height  
 * Available when nocompatible: true
 */
.scrollbar-h-{size} {
  --scrollbar-height: {size-value};
}

/* Examples */
.scrollbar-w-1 { --scrollbar-width: 0.25rem; }
.scrollbar-w-4 { --scrollbar-width: 1rem; }
.scrollbar-w-8 { --scrollbar-width: 2rem; }
.scrollbar-h-2 { --scrollbar-height: 0.5rem; }
.scrollbar-h-6 { --scrollbar-height: 1.5rem; }
.scrollbar-w-[3px] { --scrollbar-width: 3px; }

Usage Examples:

<!-- Custom width scrollbar -->
<div class="scrollbar scrollbar-w-2 overflow-auto h-64">
  <div class="h-96">Content with 2-unit wide scrollbar</div>
</div>

<!-- Custom height scrollbar -->
<div class="scrollbar scrollbar-h-3 overflow-auto w-64">
  <div class="w-96">Content with 3-unit tall horizontal scrollbar</div>
</div>

<!-- Custom size both directions -->
<div class="scrollbar scrollbar-w-6 scrollbar-h-4 overflow-auto h-64 w-64">
  <div class="h-96 w-96">Custom sized scrollbars both ways</div>
</div>

<!-- Arbitrary size values -->
<div class="scrollbar scrollbar-w-[12px] scrollbar-h-[8px] overflow-auto h-64 w-64">
  <div class="h-96 w-96">Precise pixel sizing</div>
</div>

Border Radius Utilities

Border radius utilities for all scrollbar components, available when nocompatible: true is set.

/**
 * Track border radius utilities
 * Available when nocompatible: true
 */
.scrollbar-track-rounded-{value} {
  --scrollbar-track-radius: {radius-value};
}

/**
 * Thumb border radius utilities
 * Available when nocompatible: true
 */
.scrollbar-thumb-rounded-{value} {
  --scrollbar-thumb-radius: {radius-value};
}

/**
 * Corner border radius utilities
 * Available when nocompatible: true
 */
.scrollbar-corner-rounded-{value} {
  --scrollbar-corner-radius: {radius-value};
}

/* Examples */
.scrollbar-track-rounded { --scrollbar-track-radius: 0.25rem; }
.scrollbar-thumb-rounded-lg { --scrollbar-thumb-radius: 0.5rem; }
.scrollbar-corner-rounded-full { --scrollbar-corner-radius: 9999px; }
.scrollbar-track-rounded-[16px] { --scrollbar-track-radius: 16px; }

Usage Examples:

<!-- Rounded track -->
<div class="scrollbar scrollbar-track-rounded scrollbar-track-gray-200 overflow-auto h-64">
  <div class="h-96">Content with rounded track</div>
</div>

<!-- Rounded thumb -->
<div class="scrollbar scrollbar-thumb-rounded-lg scrollbar-thumb-blue-500 overflow-auto h-64">
  <div class="h-96">Content with rounded thumb</div>
</div>

<!-- Fully rounded scrollbar -->
<div class="scrollbar 
            scrollbar-track-rounded-full 
            scrollbar-thumb-rounded-full 
            scrollbar-corner-rounded-full
            scrollbar-track-gray-100 
            scrollbar-thumb-gray-400 
            overflow-auto h-64 w-64">
  <div class="h-96 w-96">Fully rounded scrollbar components</div>
</div>

<!-- Mixed radius values -->
<div class="scrollbar 
            scrollbar-track-rounded-sm 
            scrollbar-thumb-rounded-xl 
            scrollbar-corner-rounded
            scrollbar-track-blue-100 
            scrollbar-thumb-blue-500 
            overflow-auto h-64">
  <div class="h-96">Different radius values for each component</div>
</div>

<!-- Arbitrary radius values -->
<div class="scrollbar 
            scrollbar-track-rounded-[4px] 
            scrollbar-thumb-rounded-[12px] 
            scrollbar-corner-rounded-[8px]
            overflow-auto h-64 w-64">
  <div class="h-96 w-96">Custom pixel radius values</div>
</div>

Enabling Advanced Utilities

Advanced utilities are only available when the plugin is configured with nocompatible: true:

// tailwind.config.js
module.exports = {
  plugins: [
    require('tailwind-scrollbar')({
      nocompatible: true // Enables size and border radius utilities
    })
  ]
};

Without this setting, size and border radius utilities are not generated, avoiding potential compatibility issues.

Why "nocompatible" Mode?

These utilities are placed behind a compatibility flag because:

Potential Issues

CSS Variable Dependencies: Size utilities rely on CSS custom properties that may not work consistently across all browsers
WebKit-Specific: Border radius utilities only work in WebKit browsers (Safari, Chrome)
Layout Conflicts: Custom sizing may interfere with existing layout systems
Accessibility: Very small or large scrollbars may create accessibility issues

Safe Usage

Enable nocompatible mode when:

Targeting modern browsers primarily
You need fine-grained scrollbar control
You're willing to test thoroughly across browsers
Your design system requires specific scrollbar dimensions

Complete Advanced Example

<!-- Comprehensive advanced scrollbar styling -->
<div class="scrollbar 
            scrollbar-w-3 
            scrollbar-h-3 
            scrollbar-track-gray-100 
            scrollbar-thumb-indigo-500 
            scrollbar-corner-gray-50
            scrollbar-track-rounded-lg 
            scrollbar-thumb-rounded-full 
            scrollbar-corner-rounded
            scrollbar-track-hover:scrollbar-track-gray-200 
            scrollbar-hover:scrollbar-thumb-indigo-600 
            scrollbar-active:scrollbar-thumb-indigo-700
            overflow-auto h-64 w-64 p-4 border border-gray-200">
  <div class="h-96 w-96 bg-gradient-to-br from-blue-50 to-indigo-100 p-4">
    <h3 class="text-lg font-semibold mb-4">Advanced Scrollbar</h3>
    <p>This scrollbar demonstrates:</p>
    <ul class="list-disc ml-6 space-y-2">
      <li>Custom size (3 units wide/tall)</li>
      <li>Custom colors with opacity</li>
      <li>Border radius on all components</li>
      <li>Interactive hover/active states</li>
      <li>Overflow in both directions</li>
    </ul>
    <div class="mt-8 h-32 bg-white/50 rounded p-4">
      Extra content to ensure overflow...
    </div>
  </div>
</div>

Theme Integration

Advanced utilities integrate with Tailwind's theme system:

Size Values

// Uses theme.width and theme.height
module.exports = {
  theme: {
    extend: {
      width: {
        'scrollbar': '14px',
        'scrollbar-thin': '6px'
      },
      height: {
        'scrollbar': '14px', 
        'scrollbar-thin': '6px'
      }
    }
  }
};

<div class="scrollbar scrollbar-w-scrollbar scrollbar-h-scrollbar-thin">
  Custom themed sizes
</div>

Border Radius Values

// Uses theme.borderRadius
module.exports = {
  theme: {
    extend: {
      borderRadius: {
        'scrollbar': '6px'
      }
    }
  }
};

<div class="scrollbar scrollbar-thumb-rounded-scrollbar">
  Custom themed border radius
</div>

Responsive Advanced Utilities

Advanced utilities work with Tailwind's responsive system:

<!-- Responsive scrollbar sizing -->
<div class="scrollbar 
            scrollbar-w-2 
            md:scrollbar-w-4 
            lg:scrollbar-w-6 
            scrollbar-thumb-rounded 
            md:scrollbar-thumb-rounded-lg 
            lg:scrollbar-thumb-rounded-xl">
  Responsive scrollbar size and border radius
</div>

Browser Support

Size Utilities

WebKit browsers (Safari, Chrome): Full support
Firefox: Limited support (may not respect custom sizing)
Older browsers: May fall back to default sizes

Border Radius Utilities

WebKit browsers (Safari, Chrome): Full support
Firefox: Not supported (uses system scrollbar appearance)
Other browsers: Varies by implementation

Best Practices

Performance

<!-- Good: Minimal custom properties -->
<div class="scrollbar scrollbar-w-4 scrollbar-thumb-rounded">
  Efficient use of custom properties
</div>

<!-- Avoid: Excessive customization -->
<div class="scrollbar scrollbar-w-[13.7px] scrollbar-h-[11.3px] scrollbar-track-rounded-[2.5px]">
  Overly specific values may impact performance
</div>

Accessibility

<!-- Good: Reasonable sizes -->
<div class="scrollbar scrollbar-w-4">
  Large enough to interact with easily
</div>

<!-- Avoid: Too small -->
<div class="scrollbar scrollbar-w-1">
  May be difficult to click/drag
</div>

Browser Testing

Always test advanced utilities across target browsers, especially:

Size consistency in different browsers
Border radius appearance
Interactive state behavior
Mobile device support

Install with Tessl CLI

npx tessl i tessl/npm-tailwind-scrollbar

docs

advanced-utilities.md

interactive-states.md

plugin-configuration.md

tile.json

tessl/npm-tailwind-scrollbar