0
# Tailwind Scrollbar
1

2
Tailwind Scrollbar is a Tailwind CSS plugin that provides comprehensive scrollbar styling utilities with cross-browser support. It addresses the fragmented scrollbar styling landscape by providing a unified API that handles both the Firefox/Chromium standard (scrollbar-width, scrollbar-color) and the WebKit pseudoelement approach (::-webkit-scrollbar) used by other browsers.
3

4
## Package Information
5

6
- **Package Name**: tailwind-scrollbar
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev tailwind-scrollbar`
10

11
## Core Imports
12

13
```javascript
14
// Import as CSS using Tailwind v4 syntax
15
@import 'tailwindcss';
16
@plugin 'tailwind-scrollbar';
17
```
18

19
Or using JavaScript configuration:
20

21
```javascript
22
const scrollbarPlugin = require('tailwind-scrollbar');
23

24
module.exports = {
25
  plugins: [
26
    scrollbarPlugin(options)
27
  ]
28
};
29
```
30

31
## Basic Usage
32

33
```html
34
<!-- Enable custom scrollbar with default styling -->
35
<div class="scrollbar overflow-auto h-64">
36
  <div class="h-96">Content that overflows...</div>
37
</div>
38

39
<!-- Style scrollbar colors -->
40
<div class="scrollbar scrollbar-track-gray-100 scrollbar-thumb-gray-400 overflow-auto h-64">
41
  <div class="h-96">Content with custom colors...</div>
42
</div>
43

44
<!-- Use thin scrollbar -->
45
<div class="scrollbar-thin scrollbar-thumb-blue-500 overflow-auto h-64">
46
  <div class="h-96">Content with thin scrollbar...</div>
47
</div>
48

49
<!-- Hide scrollbar completely -->
50
<div class="scrollbar-none overflow-auto h-64">
51
  <div class="h-96">Content with hidden scrollbar...</div>
52
</div>
53
```
54

55
## Architecture
56

57
Tailwind Scrollbar is built around several key components:
58

59
- **Plugin Factory**: Main export that creates a Tailwind CSS plugin with configurable options
60
- **Utility Generation**: Functions that generate CSS utilities for different scrollbar aspects
61
- **Browser Strategy Handling**: Conditional CSS generation based on browser compatibility preferences
62
- **Component System**: Unified API for styling track, thumb, and corner scrollbar components
63

64
## Capabilities
65

66
### Plugin Configuration
67

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

70
```javascript { .api }
71
/**
72
 * Creates a Tailwind CSS plugin for scrollbar styling utilities
73
 * @param options - Configuration options for the plugin
74
 * @returns Tailwind CSS plugin instance
75
 */
76
function plugin(options?: PluginOptions): TailwindPlugin;
77

78
const plugin = require('tailwind-scrollbar');
79
```
80

81
[Plugin Configuration](./plugin-configuration.md)
82

83
### Base Scrollbar Utilities
84

85
Fundamental scrollbar control utilities that enable, modify, or hide scrollbars entirely.
86

87
```css { .api }
88
.scrollbar { /* Enable custom scrollbar with 16px default size */ }
89
.scrollbar-thin { /* Enable thin scrollbar with 8px size */ }
90
.scrollbar-none { /* Hide scrollbar completely */ }
91
```
92

93
[Base Utilities](./base-utilities.md)
94

95
### Color Utilities
96

97
Comprehensive color styling for all scrollbar components using Tailwind's color system.
98

99
```css { .api }
100
.scrollbar-track-{color} { /* Set track background color */ }
101
.scrollbar-thumb-{color} { /* Set thumb background color */ }
102
.scrollbar-corner-{color} { /* Set corner background color */ }
103
```
104

105
[Color Utilities](./color-utilities.md)
106

107
### Interactive States
108

109
Hover and active state variants for scrollbar components using WebKit pseudoelements.
110

111
```css { .api }
112
.scrollbar-hover:scrollbar-thumb-{color} { /* Thumb hover state */ }
113
.scrollbar-track-hover:scrollbar-track-{color} { /* Track hover state */ }
114
.scrollbar-corner-hover:scrollbar-corner-{color} { /* Corner hover state */ }
115
.scrollbar-active:scrollbar-thumb-{color} { /* Thumb active state */ }
116
.scrollbar-track-active:scrollbar-track-{color} { /* Track active state */ }
117
```
118

119
[Interactive States](./interactive-states.md)
120

121
### Advanced Utilities
122

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

125
```css { .api }
126
.scrollbar-w-{size} { /* Set scrollbar width */ }
127
.scrollbar-h-{size} { /* Set scrollbar height */ }
128
.scrollbar-{component}-rounded-{value} { /* Set component border radius */ }
129
```
130

131
[Advanced Utilities](./advanced-utilities.md)
132

133
### Helper Functions
134

135
Utility functions that may be useful when extending or working with the plugin.
136

137
```javascript { .api }
138
/**
139
 * Gets the underlying default import of a module.
140
 * Handles differences between ESM and CommonJS imports for Tailwind internal modules.
141
 */
142
function importDefault<T>(mod: T | { __esModule: unknown, default: T }): T;
143
```
144

145
[Helper Functions](./helpers.md)
146

147
## Types
148

149
```javascript { .api }
150
/**
151
 * Plugin options for configuring scrollbar behavior
152
 */
153
interface PluginOptions {
154
  /** Browser compatibility strategy - 'standard' uses modern properties, 'pseudoelements' prioritizes WebKit approach */
155
  preferredStrategy?: 'standard' | 'pseudoelements';
156
  /** Alternative lowercase spelling of preferredStrategy for compatibility */
157
  preferredstrategy?: 'standard' | 'pseudoelements';
158
  /** Enable additional size and rounded utilities (may cause compatibility issues) */
159
  nocompatible?: boolean;
160
}
161

162
/**
163
 * Tailwind plugin interface used internally
164
 */
165
interface TailwindPlugin {
166
  /** Add base styles to Tailwind */
167
  addBase: (styles: Record<string, any>) => void;
168
  /** Add utilities to Tailwind */
169
  addUtilities: (utilities: Record<string, any>) => void;
170
  /** Add dynamic utilities based on theme values */
171
  matchUtilities: (utilities: Record<string, Function>, options: { values: Record<string, any>, type?: string }) => void;
172
  /** Access Tailwind theme configuration */
173
  theme: (key: string) => any;
174
  /** Add variant modifiers */
175
  addVariant: (name: string, selector: string) => void;
176
  /** Access Tailwind configuration */
177
  config: (key: string) => any;
178
}
179
```