Plugin Configuration

Core plugin setup and configuration options for controlling scrollbar styling behavior and browser compatibility strategies.

Capabilities

Plugin Factory Function

The main export that creates a Tailwind CSS plugin with configurable options.

/**
 * Creates a Tailwind CSS plugin for scrollbar styling utilities
 * @param options - Configuration options for the plugin
 * @returns Tailwind CSS plugin instance
 */
function plugin(options?: PluginOptions): TailwindPlugin;

const plugin = require('tailwind-scrollbar');

Usage Examples:

// Basic plugin registration with Tailwind v3
module.exports = {
  plugins: [
    require('tailwind-scrollbar')
  ]
};

// With standard strategy (default - uses modern scrollbar properties)
module.exports = {
  plugins: [
    require('tailwind-scrollbar')({
      preferredStrategy: 'standard'
    })
  ]
};

// With pseudoelements strategy (prioritizes WebKit approach)
module.exports = {
  plugins: [
    require('tailwind-scrollbar')({
      preferredStrategy: 'pseudoelements'
    })
  ]
};

// Enable additional utilities (may cause compatibility issues)
module.exports = {
  plugins: [
    require('tailwind-scrollbar')({
      nocompatible: true
    })
  ]
};

For Tailwind v4:

@import 'tailwindcss';
@plugin 'tailwind-scrollbar';

Configuration Options

Plugin configuration object with optional properties.

/**
 * Plugin configuration options
 */
interface PluginOptions {
  /** Browser compatibility strategy */
  preferredStrategy?: 'standard' | 'pseudoelements';
  /** Alternative lowercase spelling for compatibility */
  preferredstrategy?: 'standard' | 'pseudoelements';
  /** Enable size and rounded utilities */
  nocompatible?: boolean;
}

preferredStrategy

Controls how the plugin handles browser compatibility differences:

• 'standard' (default): Uses modern scrollbar-width and scrollbar-color properties alongside WebKit pseudoelements
• 'pseudoelements': Wraps standard properties in Firefox-only support queries, prioritizing WebKit pseudoelement approach

Standard Strategy CSS Output:

.scrollbar {
  scrollbar-width: auto;
  scrollbar-color: var(--scrollbar-thumb, initial) var(--scrollbar-track, initial);
  /* WebKit rules also included */
}

Pseudoelements Strategy CSS Output:

.scrollbar {
  @supports (-moz-appearance:none) {
    scrollbar-width: auto;
    scrollbar-color: var(--scrollbar-thumb, initial) var(--scrollbar-track, initial);
  }
  /* WebKit rules also included */
}

nocompatible

When set to true, enables additional utilities that may cause compatibility issues:

• scrollbar-w-{size} and scrollbar-h-{size} utilities
• scrollbar-{component}-rounded-{value} utilities for border radius

Usage Example:

require('tailwind-scrollbar')({ nocompatible: true })

Enabled Utilities:

<div class="scrollbar scrollbar-w-4 scrollbar-h-4">Content</div>
<div class="scrollbar scrollbar-thumb-rounded-lg">Content</div>

Browser Strategy Details

The plugin handles the fragmented scrollbar styling landscape by supporting both modern standards and legacy WebKit approaches:

Modern Standards (Firefox/Chromium)

• Uses scrollbar-width property for sizing
• Uses scrollbar-color property for colors
• Limited styling options but consistent behavior

WebKit Pseudoelements (Safari/older browsers)

• Uses ::-webkit-scrollbar family of pseudoelements
• Supports detailed styling including size, colors, and border radius
• More flexible but browser-specific

Strategy Selection

Standard Strategy is recommended for:

• Modern applications targeting recent browsers
• Applications where consistent behavior across browsers is more important than visual customization
• Situations where you want to leverage the latest web standards

Pseudoelements Strategy is recommended for:

• Applications requiring maximum visual consistency across older browsers
• Situations where WebKit-based browsers (Safari, older Chrome) are the primary target
• When you need more detailed scrollbar customization

Plugin Initialization Process

The plugin performs these steps during Tailwind CSS compilation:

1. Validates Options: Checks preferredStrategy value and warns if invalid
2. Adds Base Styles: Resets scrollbar properties to initial values
3. Generates Size Utilities: Creates .scrollbar, .scrollbar-thin, .scrollbar-none utilities
4. Generates Color Utilities: Creates color utilities for all theme colors
5. Adds Variants: Registers hover and active state variants
6. Conditionally Adds Advanced Utilities: If nocompatible is true, adds size and rounded utilities

Error Handling

The plugin includes built-in validation and warning systems:

// Invalid strategy warning
if (preferredStrategy !== 'standard' && preferredStrategy !== 'pseudoelements') {
  console.warn('WARNING: tailwind-scrollbar preferredStrategy should be \'standard\' or \'pseudoelements\'');
  preferredStrategy = 'standard'; // Falls back to standard
}

This ensures the plugin continues to function even with invalid configuration.