0
# Plugin Configuration
1

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

4
## Capabilities
5

6
### Plugin Factory Function
7

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

10
```javascript { .api }
11
/**
12
 * Creates a Tailwind CSS plugin for scrollbar styling utilities
13
 * @param options - Configuration options for the plugin
14
 * @returns Tailwind CSS plugin instance
15
 */
16
function plugin(options?: PluginOptions): TailwindPlugin;
17

18
const plugin = require('tailwind-scrollbar');
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
// Basic plugin registration with Tailwind v3
25
module.exports = {
26
  plugins: [
27
    require('tailwind-scrollbar')
28
  ]
29
};
30

31
// With standard strategy (default - uses modern scrollbar properties)
32
module.exports = {
33
  plugins: [
34
    require('tailwind-scrollbar')({
35
      preferredStrategy: 'standard'
36
    })
37
  ]
38
};
39

40
// With pseudoelements strategy (prioritizes WebKit approach)
41
module.exports = {
42
  plugins: [
43
    require('tailwind-scrollbar')({
44
      preferredStrategy: 'pseudoelements'
45
    })
46
  ]
47
};
48

49
// Enable additional utilities (may cause compatibility issues)
50
module.exports = {
51
  plugins: [
52
    require('tailwind-scrollbar')({
53
      nocompatible: true
54
    })
55
  ]
56
};
57
```
58

59
For Tailwind v4:
60

61
```css
62
@import 'tailwindcss';
63
@plugin 'tailwind-scrollbar';
64
```
65

66
### Configuration Options
67

68
Plugin configuration object with optional properties.
69

70
```javascript { .api }
71
/**
72
 * Plugin configuration options
73
 */
74
interface PluginOptions {
75
  /** Browser compatibility strategy */
76
  preferredStrategy?: 'standard' | 'pseudoelements';
77
  /** Alternative lowercase spelling for compatibility */
78
  preferredstrategy?: 'standard' | 'pseudoelements';
79
  /** Enable size and rounded utilities */
80
  nocompatible?: boolean;
81
}
82
```
83

84
#### preferredStrategy
85

86
Controls how the plugin handles browser compatibility differences:
87

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

91
**Standard Strategy CSS Output:**
92
```css
93
.scrollbar {
94
  scrollbar-width: auto;
95
  scrollbar-color: var(--scrollbar-thumb, initial) var(--scrollbar-track, initial);
96
  /* WebKit rules also included */
97
}
98
```
99

100
**Pseudoelements Strategy CSS Output:**
101
```css
102
.scrollbar {
103
  @supports (-moz-appearance:none) {
104
    scrollbar-width: auto;
105
    scrollbar-color: var(--scrollbar-thumb, initial) var(--scrollbar-track, initial);
106
  }
107
  /* WebKit rules also included */
108
}
109
```
110

111
#### nocompatible
112

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

115
- `scrollbar-w-{size}` and `scrollbar-h-{size}` utilities
116
- `scrollbar-{component}-rounded-{value}` utilities for border radius
117

118
**Usage Example:**
119
```javascript
120
require('tailwind-scrollbar')({ nocompatible: true })
121
```
122

123
**Enabled Utilities:**
124
```html
125
<div class="scrollbar scrollbar-w-4 scrollbar-h-4">Content</div>
126
<div class="scrollbar scrollbar-thumb-rounded-lg">Content</div>
127
```
128

129
### Browser Strategy Details
130

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

133
#### Modern Standards (Firefox/Chromium)
134
- Uses `scrollbar-width` property for sizing
135
- Uses `scrollbar-color` property for colors
136
- Limited styling options but consistent behavior
137

138
#### WebKit Pseudoelements (Safari/older browsers)
139
- Uses `::-webkit-scrollbar` family of pseudoelements
140
- Supports detailed styling including size, colors, and border radius
141
- More flexible but browser-specific
142

143
#### Strategy Selection
144

145
**Standard Strategy** is recommended for:
146
- Modern applications targeting recent browsers
147
- Applications where consistent behavior across browsers is more important than visual customization
148
- Situations where you want to leverage the latest web standards
149

150
**Pseudoelements Strategy** is recommended for:
151
- Applications requiring maximum visual consistency across older browsers
152
- Situations where WebKit-based browsers (Safari, older Chrome) are the primary target
153
- When you need more detailed scrollbar customization
154

155
### Plugin Initialization Process
156

157
The plugin performs these steps during Tailwind CSS compilation:
158

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

166
### Error Handling
167

168
The plugin includes built-in validation and warning systems:
169

170
```javascript
171
// Invalid strategy warning
172
if (preferredStrategy !== 'standard' && preferredStrategy !== 'pseudoelements') {
173
  console.warn('WARNING: tailwind-scrollbar preferredStrategy should be \'standard\' or \'pseudoelements\'');
174
  preferredStrategy = 'standard'; // Falls back to standard
175
}
176
```
177

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