0
# jQuery Integration
1

2
OverlayScrollbars provides seamless jQuery integration through a dedicated plugin file that extends jQuery's prototype with the `overlayScrollbars()` method, enabling natural jQuery chaining and selector usage.
3

4
## jQuery Plugin Setup
5

6
### Including the jQuery Plugin
7

8
```html
9
<!-- Include jQuery first -->
10
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
11

12
<!-- Include OverlayScrollbars CSS -->
13
<link rel="stylesheet" href="overlayscrollbars/css/OverlayScrollbars.min.css">
14

15
<!-- Include jQuery plugin version -->
16
<script src="overlayscrollbars/js/jquery.overlayScrollbars.min.js"></script>
17
```
18

19
### Module Import
20

21
```javascript
22
// ES modules
23
import $ from "jquery";
24
import "overlayscrollbars/js/jquery.overlayScrollbars.min.js";
25

26
// CommonJS
27
const $ = require("jquery");
28
require("overlayscrollbars/js/jquery.overlayScrollbars.min.js");
29
```
30

31
## jQuery Plugin API
32

33
### $.fn.overlayScrollbars()
34

35
```javascript { .api }
36
interface JQuery {
37
  overlayScrollbars(
38
    options: OverlayScrollbarsOptions,
39
    extensions?: OverlayScrollbarsExtensions
40
  ): JQuery;
41
  
42
  overlayScrollbars(): OverlayScrollbarsInstance | OverlayScrollbarsInstance[];
43
}
44
```
45

46
The jQuery plugin method behaves differently based on the arguments provided:
47

48
- **With options object**: Initializes OverlayScrollbars and returns jQuery object for chaining
49
- **Without arguments or non-object first argument**: Returns OverlayScrollbars instance(s)
50

51
## Basic jQuery Usage
52

53
### Initialization
54

55
```javascript
56
// Initialize with default options
57
$('.content').overlayScrollbars({});
58

59
// Initialize with custom options
60
$('.scrollable').overlayScrollbars({
61
  className: "os-theme-dark",
62
  scrollbars: {
63
    autoHide: "leave",
64
    autoHideDelay: 1000
65
  },
66
  callbacks: {
67
    onScroll: function() {
68
      console.log('jQuery: Scrolling...');
69
    }
70
  }
71
});
72

73
// jQuery chaining
74
$('.content')
75
  .overlayScrollbars({
76
    resize: "both",
77
    scrollbars: { visibility: "auto" }
78
  })
79
  .addClass('initialized')
80
  .fadeIn();
81
```
82

83
### Getting Instances
84

85
```javascript
86
// Get OverlayScrollbars instances (not jQuery objects)
87
const instances = $('.content').overlayScrollbars();
88

89
// Single element - returns single instance
90
const instance = $('#main-content').overlayScrollbars();
91

92
// Multiple elements - returns array of instances
93
const instanceArray = $('.multiple-content').overlayScrollbars();
94
```
95

96
## jQuery-specific Patterns
97

98
### Event Handling with jQuery
99

100
```javascript
101
$('.content').overlayScrollbars({
102
  callbacks: {
103
    onInitialized: function(instance) {
104
      // jQuery event trigger
105
      $(instance.getElements('target')).trigger('os:initialized');
106
    },
107
    
108
    onScroll: function(instance) {
109
      const $target = $(instance.getElements('target'));
110
      $target.trigger('os:scroll', [instance]);
111
    },
112
    
113
    onDestroyed: function(instance) {
114
      $(instance.getElements('target')).trigger('os:destroyed');
115
    }
116
  }
117
});
118

119
// Listen for custom events
120
$('.content').on('os:scroll', function(event, instance) {
121
  console.log('OverlayScrollbars scroll event triggered');
122
});
123
```
124

125
### Integration with jQuery UI
126

127
```javascript
128
// Use with jQuery UI widgets
129
$('.content')
130
  .overlayScrollbars({
131
    scrollbars: { autoHide: "leave" }
132
  })
133
  .resizable({
134
    resize: function() {
135
      // Update OverlayScrollbars when resized
136
      $(this).overlayScrollbars().update(true);
137
    }
138
  });
139

140
// Tab integration
141
$('#tabs').tabs({
142
  activate: function(event, ui) {
143
    // Update scrollbars in newly activated tab
144
    ui.newPanel.find('.scrollable').each(function() {
145
      const instance = $(this).overlayScrollbars();
146
      if (instance) {
147
        instance.update();
148
      }
149
    });
150
  }
151
});
152
```
153

154
### Dynamic Content with jQuery
155

156
```javascript
157
// Initialize scrollbars
158
$('.dynamic-content').overlayScrollbars({
159
  callbacks: {
160
    onContentSizeChanged: function(instance) {
161
      console.log('Content size changed via jQuery');
162
    }
163
  }
164
});
165

166
// Add content dynamically
167
$('.add-content-btn').click(function() {
168
  const $content = $('.dynamic-content');
169
  
170
  // Add new content
171
  $content.append('<div class="new-item">New content item</div>');
172
  
173
  // Update OverlayScrollbars
174
  $content.overlayScrollbars().update();
175
});
176

177
// AJAX content loading
178
$.get('/api/content', function(data) {
179
  $('.ajax-content')
180
    .html(data)
181
    .overlayScrollbars() // Get instance
182
    .update(true); // Force update
183
});
184
```
185

186
### jQuery Animation Integration
187

188
```javascript
189
// Animate and scroll
190
$('.content').overlayScrollbars({
191
  scrollbars: { autoHide: "scroll" }
192
});
193

194
$('.scroll-to-bottom').click(function() {
195
  const instance = $('.content').overlayScrollbars();
196
  
197
  // Scroll with OverlayScrollbars animation
198
  instance.scroll({ y: '100%' }, 1000, 'swing', function() {
199
    // Animation complete - trigger jQuery animation
200
    $('.content').effect('highlight', { color: '#ff0' }, 500);
201
  });
202
});
203
```
204

205
### Responsive Design with jQuery
206

207
```javascript
208
$(window).resize(function() {
209
  // Update all OverlayScrollbars instances on window resize
210
  $('.scrollable').each(function() {
211
    const instance = $(this).overlayScrollbars();
212
    if (instance && !instance.getState().destroyed) {
213
      instance.update(true);
214
    }
215
  });
216
});
217

218
// Media query handling
219
function handleMediaChange(mq) {
220
  if (mq.matches) {
221
    // Mobile view - different scrollbar settings
222
    $('.content').overlayScrollbars().options({
223
      scrollbars: {
224
        touchSupport: true,
225
        autoHide: "leave"
226
      }
227
    });
228
  } else {
229
    // Desktop view
230
    $('.content').overlayScrollbars().options({
231
      scrollbars: {
232
        touchSupport: false,
233
        autoHide: "scroll"
234
      }
235
    });
236
  }
237
}
238

239
const mediaQuery = window.matchMedia('(max-width: 768px)');
240
mediaQuery.addListener(handleMediaChange);
241
handleMediaChange(mediaQuery);
242
```
243

244
## jQuery Plugin Examples
245

246
### Complete Setup Example
247

248
```javascript
249
$(document).ready(function() {
250
  // Initialize OverlayScrollbars on all scrollable elements
251
  $('.scrollable').overlayScrollbars({
252
    className: "os-theme-thin-dark",
253
    resize: "none",
254
    scrollbars: {
255
      visibility: "auto",
256
      autoHide: "leave",
257
      autoHideDelay: 800,
258
      dragScrolling: true,
259
      clickScrolling: false,
260
      touchSupport: true
261
    },
262
    callbacks: {
263
      onInitialized: function() {
264
        console.log('OverlayScrollbars initialized via jQuery');
265
      },
266
      onScroll: function(instance) {
267
        // Update scroll indicator
268
        const state = instance.getState();
269
        const scrollPercent = (state.viewportSize.height / state.contentScrollSize.height) * 100;
270
        $('.scroll-indicator').width(scrollPercent + '%');
271
      }
272
    }
273
  });
274

275
  // Navigation scroll links
276
  $('.nav-link').click(function(e) {
277
    e.preventDefault();
278
    const target = $(this).attr('href');
279
    const instance = $('.main-content').overlayScrollbars();
280
    
281
    instance.scroll(target, 800, 'easeInOutQuad');
282
  });
283

284
  // Destroy on modal close
285
  $('.modal').on('hidden.bs.modal', function() {
286
    $(this).find('.scrollable').overlayScrollbars().destroy();
287
  });
288
});
289
```
290

291
### Form Integration
292

293
```javascript
294
// Textarea with OverlayScrollbars
295
$('textarea.enhanced').overlayScrollbars({
296
  className: "os-theme-minimal",
297
  textarea: {
298
    dynHeight: false,
299
    dynWidth: false
300
  },
301
  scrollbars: {
302
    visibility: "auto",
303
    autoHide: "never"
304
  }
305
});
306

307
// Form validation with scroll to error
308
$('#myForm').on('submit', function() {
309
  const $firstError = $(this).find('.error').first();
310
  if ($firstError.length) {
311
    const instance = $('.form-container').overlayScrollbars();
312
    instance.scroll($firstError[0], 500);
313
    return false;
314
  }
315
});
316
```
317

318
## Compatibility Notes
319

320
- **jQuery Version**: Requires jQuery 1.9.1 or higher (excluding jQuery slim)
321
- **Method Chaining**: Full support for jQuery chaining when initializing
322
- **Event System**: Integrates with jQuery's event system through callbacks
323
- **Element Selection**: Works with all jQuery selectors and traversal methods
324

325
## Migration from Other Scrollbar Libraries
326

327
```javascript
328
// Replace other jQuery scrollbar plugins
329
$('.content')
330
  // .customScrollbar('destroy') // Remove old plugin
331
  .overlayScrollbars({
332
    scrollbars: {
333
      visibility: "auto",
334
      autoHide: "scroll"
335
    }
336
  });
337
```
338

339
## Types
340

341
```javascript { .api }
342
interface JQuery {
343
  overlayScrollbars(
344
    options: OverlayScrollbarsOptions,
345
    extensions?: OverlayScrollbarsExtensions
346
  ): JQuery;
347
  
348
  overlayScrollbars(
349
    action?: string | function
350
  ): OverlayScrollbarsInstance | OverlayScrollbarsInstance[];
351
}
352

353
// jQuery-specific event data
354
interface JQueryOverlayScrollbarsEventData {
355
  instance: OverlayScrollbarsInstance;
356
  state: OverlayScrollbarsState;
357
  elements: OverlayScrollbarsElements;
358
}
359
```