0
# Initialization and Management
1

2
Core functionality for creating and managing OverlayScrollbars instances, including constructor usage patterns and instance lifecycle management.
3

4
## Constructor
5

6
```javascript { .api }
7
function OverlayScrollbars(
8
  target: Element | NodeList | string,
9
  options?: OverlayScrollbarsOptions,
10
  extensions?: OverlayScrollbarsExtensions
11
): OverlayScrollbarsInstance | OverlayScrollbarsInstance[];
12
```
13

14
**Parameters:**
15
- `target` - Element(s) to apply scrollbars to. Can be a single Element, NodeList, or selector string
16
- `options` - Configuration options object (optional)
17
- `extensions` - Extensions to initialize with the instance (optional)
18

19
**Returns:** Single instance for single elements, array of instances for multiple elements
20

21
## Usage Examples
22

23
### Single Element Initialization
24

25
```javascript
26
// Initialize with minimal options
27
const instance = OverlayScrollbars(document.querySelector('.content'), {});
28

29
// Initialize with configuration
30
const instance = OverlayScrollbars(document.getElementById('main'), {
31
  className: "os-theme-dark",
32
  resize: "both",
33
  scrollbars: {
34
    autoHide: "leave",
35
    autoHideDelay: 1000
36
  }
37
});
38
```
39

40
### Multiple Elements Initialization
41

42
```javascript
43
// Initialize multiple elements with same options
44
const instances = OverlayScrollbars(document.querySelectorAll('.scrollable'), {
45
  scrollbars: {
46
    visibility: "auto"
47
  }
48
});
49

50
// Access individual instances
51
instances.forEach((instance, index) => {
52
  console.log(`Instance ${index} initialized`);
53
});
54
```
55

56
### Query-based Initialization
57

58
```javascript
59
// Using selector strings
60
const instances = OverlayScrollbars('.content, .sidebar', {
61
  className: "custom-theme"
62
});
63
```
64

65
### With Extensions
66

67
```javascript
68
const instance = OverlayScrollbars(element, {
69
  scrollbars: { autoHide: "scroll" }
70
}, {
71
  // Extension configuration
72
  customExtension: { option: true }
73
});
74
```
75

76
## Instance Retrieval
77

78
You can retrieve existing instances without reinitializing:
79

80
```javascript
81
// Get existing instance (returns undefined if not initialized)
82
const existingInstance = OverlayScrollbars(element);
83

84
// Get multiple existing instances
85
const existingInstances = OverlayScrollbars(document.querySelectorAll('.content'));
86
```
87

88
## Conditional Initialization
89

90
```javascript
91
// Initialize only elements that match condition
92
const instances = OverlayScrollbars(document.querySelectorAll('.content'), '!');
93
// Returns only valid, non-destroyed instances
94

95
// Initialize with custom condition function
96
const instances = OverlayScrollbars(
97
  document.querySelectorAll('.content'),
98
  (element, existingInstance) => {
99
    // Return true to include this element
100
    return element.scrollHeight > element.clientHeight;
101
  }
102
);
103
```
104

105
## Instance State Management
106

107
```javascript { .api }
108
interface OverlayScrollbarsInstance {
109
  getState(property?: string): OverlayScrollbarsState | any;
110
  getElements(elementName?: string): OverlayScrollbarsElements | Element;
111
}
112
```
113

114
### Getting Instance State
115

116
```javascript
117
const instance = OverlayScrollbars(element, {});
118

119
// Get complete state
120
const state = instance.getState();
121
console.log(state.destroyed); // false
122
console.log(state.sleeping); // false
123
console.log(state.autoUpdate); // auto-update status
124

125
// Get specific state property
126
const isDestroyed = instance.getState('destroyed');
127
```
128

129
### Getting Instance Elements
130

131
```javascript
132
// Get all internal elements
133
const elements = instance.getElements();
134
console.log(elements.target); // Original target element
135
console.log(elements.host); // Host wrapper element
136
console.log(elements.viewport); // Viewport element
137
console.log(elements.content); // Content wrapper element
138

139
// Get specific element
140
const viewport = instance.getElements('viewport');
141
```
142

143
## Sleep Mode
144

145
Put instances to sleep to disable automatic updates:
146

147
```javascript { .api }
148
OverlayScrollbarsInstance.prototype.sleep(): OverlayScrollbarsInstance;
149
```
150

151
```javascript
152
// Put instance to sleep (disables auto-updates)
153
instance.sleep();
154

155
// Wake up with manual update
156
instance.update();
157
```
158

159
## Types
160

161
```javascript { .api }
162
interface OverlayScrollbarsState {
163
  destroyed: boolean;
164
  sleeping: boolean;
165
  autoUpdate: boolean | null;
166
  widthAuto: boolean;
167
  heightAuto: boolean;
168
  padding: { t: number; r: number; b: number; l: number };
169
  overflowAmount: { x: number; y: number };
170
  hideOverflow: { x: boolean; y: boolean };
171
  hasOverflow: { x: boolean; y: boolean };
172
  contentScrollSize: { width: number; height: number };
173
  viewportSize: { width: number; height: number };
174
  hostSize: { width: number; height: number };
175
}
176

177
interface OverlayScrollbarsElements {
178
  target: Element;
179
  host: Element;
180
  padding: Element;
181
  viewport: Element;
182
  content: Element;
183
  scrollbarHorizontal: { scrollbar: Element; track: Element; handle: Element };
184
  scrollbarVertical: { scrollbar: Element; track: Element; handle: Element };
185
  scrollbarCorner: Element;
186
}
187
```