0
# Advanced Utilities
1

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

4
## Capabilities
5

6
### Size Utilities
7

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

10
```css { .api }
11
/**
12
 * Scrollbar width utilities - sets custom scrollbar width
13
 * Available when nocompatible: true
14
 */
15
.scrollbar-w-{size} {
16
  --scrollbar-width: {size-value};
17
}
18

19
/**
20
 * Scrollbar height utilities - sets custom scrollbar height  
21
 * Available when nocompatible: true
22
 */
23
.scrollbar-h-{size} {
24
  --scrollbar-height: {size-value};
25
}
26

27
/* Examples */
28
.scrollbar-w-1 { --scrollbar-width: 0.25rem; }
29
.scrollbar-w-4 { --scrollbar-width: 1rem; }
30
.scrollbar-w-8 { --scrollbar-width: 2rem; }
31
.scrollbar-h-2 { --scrollbar-height: 0.5rem; }
32
.scrollbar-h-6 { --scrollbar-height: 1.5rem; }
33
.scrollbar-w-[3px] { --scrollbar-width: 3px; }
34
```
35

36
**Usage Examples:**
37
```html
38
<!-- Custom width scrollbar -->
39
<div class="scrollbar scrollbar-w-2 overflow-auto h-64">
40
  <div class="h-96">Content with 2-unit wide scrollbar</div>
41
</div>
42

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

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

53
<!-- Arbitrary size values -->
54
<div class="scrollbar scrollbar-w-[12px] scrollbar-h-[8px] overflow-auto h-64 w-64">
55
  <div class="h-96 w-96">Precise pixel sizing</div>
56
</div>
57
```
58

59
### Border Radius Utilities
60

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

63
```css { .api }
64
/**
65
 * Track border radius utilities
66
 * Available when nocompatible: true
67
 */
68
.scrollbar-track-rounded-{value} {
69
  --scrollbar-track-radius: {radius-value};
70
}
71

72
/**
73
 * Thumb border radius utilities
74
 * Available when nocompatible: true
75
 */
76
.scrollbar-thumb-rounded-{value} {
77
  --scrollbar-thumb-radius: {radius-value};
78
}
79

80
/**
81
 * Corner border radius utilities
82
 * Available when nocompatible: true
83
 */
84
.scrollbar-corner-rounded-{value} {
85
  --scrollbar-corner-radius: {radius-value};
86
}
87

88
/* Examples */
89
.scrollbar-track-rounded { --scrollbar-track-radius: 0.25rem; }
90
.scrollbar-thumb-rounded-lg { --scrollbar-thumb-radius: 0.5rem; }
91
.scrollbar-corner-rounded-full { --scrollbar-corner-radius: 9999px; }
92
.scrollbar-track-rounded-[16px] { --scrollbar-track-radius: 16px; }
93
```
94

95
**Usage Examples:**
96
```html
97
<!-- Rounded track -->
98
<div class="scrollbar scrollbar-track-rounded scrollbar-track-gray-200 overflow-auto h-64">
99
  <div class="h-96">Content with rounded track</div>
100
</div>
101

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

107
<!-- Fully rounded scrollbar -->
108
<div class="scrollbar 
109
            scrollbar-track-rounded-full 
110
            scrollbar-thumb-rounded-full 
111
            scrollbar-corner-rounded-full
112
            scrollbar-track-gray-100 
113
            scrollbar-thumb-gray-400 
114
            overflow-auto h-64 w-64">
115
  <div class="h-96 w-96">Fully rounded scrollbar components</div>
116
</div>
117

118
<!-- Mixed radius values -->
119
<div class="scrollbar 
120
            scrollbar-track-rounded-sm 
121
            scrollbar-thumb-rounded-xl 
122
            scrollbar-corner-rounded
123
            scrollbar-track-blue-100 
124
            scrollbar-thumb-blue-500 
125
            overflow-auto h-64">
126
  <div class="h-96">Different radius values for each component</div>
127
</div>
128

129
<!-- Arbitrary radius values -->
130
<div class="scrollbar 
131
            scrollbar-track-rounded-[4px] 
132
            scrollbar-thumb-rounded-[12px] 
133
            scrollbar-corner-rounded-[8px]
134
            overflow-auto h-64 w-64">
135
  <div class="h-96 w-96">Custom pixel radius values</div>
136
</div>
137
```
138

139
### Enabling Advanced Utilities
140

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

143
```javascript
144
// tailwind.config.js
145
module.exports = {
146
  plugins: [
147
    require('tailwind-scrollbar')({
148
      nocompatible: true // Enables size and border radius utilities
149
    })
150
  ]
151
};
152
```
153

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

156
### Why "nocompatible" Mode?
157

158
These utilities are placed behind a compatibility flag because:
159

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

166
#### Safe Usage
167
Enable `nocompatible` mode when:
168
- Targeting modern browsers primarily
169
- You need fine-grained scrollbar control
170
- You're willing to test thoroughly across browsers
171
- Your design system requires specific scrollbar dimensions
172

173
### Complete Advanced Example
174

175
```html
176
<!-- Comprehensive advanced scrollbar styling -->
177
<div class="scrollbar 
178
            scrollbar-w-3 
179
            scrollbar-h-3 
180
            scrollbar-track-gray-100 
181
            scrollbar-thumb-indigo-500 
182
            scrollbar-corner-gray-50
183
            scrollbar-track-rounded-lg 
184
            scrollbar-thumb-rounded-full 
185
            scrollbar-corner-rounded
186
            scrollbar-track-hover:scrollbar-track-gray-200 
187
            scrollbar-hover:scrollbar-thumb-indigo-600 
188
            scrollbar-active:scrollbar-thumb-indigo-700
189
            overflow-auto h-64 w-64 p-4 border border-gray-200">
190
  <div class="h-96 w-96 bg-gradient-to-br from-blue-50 to-indigo-100 p-4">
191
    <h3 class="text-lg font-semibold mb-4">Advanced Scrollbar</h3>
192
    <p>This scrollbar demonstrates:</p>
193
    <ul class="list-disc ml-6 space-y-2">
194
      <li>Custom size (3 units wide/tall)</li>
195
      <li>Custom colors with opacity</li>
196
      <li>Border radius on all components</li>
197
      <li>Interactive hover/active states</li>
198
      <li>Overflow in both directions</li>
199
    </ul>
200
    <div class="mt-8 h-32 bg-white/50 rounded p-4">
201
      Extra content to ensure overflow...
202
    </div>
203
  </div>
204
</div>
205
```
206

207
### Theme Integration
208

209
Advanced utilities integrate with Tailwind's theme system:
210

211
#### Size Values
212
```javascript
213
// Uses theme.width and theme.height
214
module.exports = {
215
  theme: {
216
    extend: {
217
      width: {
218
        'scrollbar': '14px',
219
        'scrollbar-thin': '6px'
220
      },
221
      height: {
222
        'scrollbar': '14px', 
223
        'scrollbar-thin': '6px'
224
      }
225
    }
226
  }
227
};
228
```
229

230
```html
231
<div class="scrollbar scrollbar-w-scrollbar scrollbar-h-scrollbar-thin">
232
  Custom themed sizes
233
</div>
234
```
235

236
#### Border Radius Values
237
```javascript
238
// Uses theme.borderRadius
239
module.exports = {
240
  theme: {
241
    extend: {
242
      borderRadius: {
243
        'scrollbar': '6px'
244
      }
245
    }
246
  }
247
};
248
```
249

250
```html
251
<div class="scrollbar scrollbar-thumb-rounded-scrollbar">
252
  Custom themed border radius
253
</div>
254
```
255

256
### Responsive Advanced Utilities
257

258
Advanced utilities work with Tailwind's responsive system:
259

260
```html
261
<!-- Responsive scrollbar sizing -->
262
<div class="scrollbar 
263
            scrollbar-w-2 
264
            md:scrollbar-w-4 
265
            lg:scrollbar-w-6 
266
            scrollbar-thumb-rounded 
267
            md:scrollbar-thumb-rounded-lg 
268
            lg:scrollbar-thumb-rounded-xl">
269
  Responsive scrollbar size and border radius
270
</div>
271
```
272

273
### Browser Support
274

275
#### Size Utilities
276
- **WebKit browsers** (Safari, Chrome): Full support
277
- **Firefox**: Limited support (may not respect custom sizing)
278
- **Older browsers**: May fall back to default sizes
279

280
#### Border Radius Utilities  
281
- **WebKit browsers** (Safari, Chrome): Full support
282
- **Firefox**: Not supported (uses system scrollbar appearance)
283
- **Other browsers**: Varies by implementation
284

285
### Best Practices
286

287
#### Performance
288
```html
289
<!-- Good: Minimal custom properties -->
290
<div class="scrollbar scrollbar-w-4 scrollbar-thumb-rounded">
291
  Efficient use of custom properties
292
</div>
293

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

300
#### Accessibility
301
```html
302
<!-- Good: Reasonable sizes -->
303
<div class="scrollbar scrollbar-w-4">
304
  Large enough to interact with easily
305
</div>
306

307
<!-- Avoid: Too small -->
308
<div class="scrollbar scrollbar-w-1">
309
  May be difficult to click/drag
310
</div>
311
```
312

313
#### Browser Testing
314
Always test advanced utilities across target browsers, especially:
315
- Size consistency in different browsers
316
- Border radius appearance
317
- Interactive state behavior
318
- Mobile device support