0
# HTML API
1

2
Automatic scrollbar initialization using HTML data attributes and global DOM observation for dynamic content.
3

4
## Capabilities
5

6
### Automatic Element Initialization
7

8
Automatically initializes SimpleBar on elements with the `data-simplebar` attribute.
9

10
```typescript { .api }
11
/**
12
 * Initialize all elements with data-simplebar attribute
13
 * Called automatically on DOM load, can be called manually for dynamic content
14
 */
15
static initDOMLoadedElements(): void;
16
```
17

18
**Usage Examples:**
19

20
```html
21
<!-- Basic automatic initialization -->
22
<div data-simplebar>
23
  <p>Content that will have custom scrollbars</p>
24
  <p>More scrollable content...</p>
25
</div>
26

27
<!-- With configuration via data attributes -->
28
<div data-simplebar data-simplebar-auto-hide="false" data-simplebar-scrollbar-min-size="30">
29
  <p>Content with custom configuration</p>
30
</div>
31
```
32

33
```typescript
34
// Manually initialize elements added after page load
35
document.body.innerHTML += '<div data-simplebar>New dynamic content</div>';
36
SimpleBar.initDOMLoadedElements();
37
```
38

39
### HTML API Initialization
40

41
Sets up the automatic HTML API with DOM observation for dynamic content.
42

43
```typescript { .api }
44
/**
45
 * Initialize the HTML API with automatic element detection
46
 * Sets up global MutationObserver to detect new elements with data-simplebar
47
 * Called automatically when SimpleBar is imported in browser environment
48
 */
49
static initHtmlApi(): void;
50
```
51

52
### Instance Management
53

54
Access existing SimpleBar instances created via HTML API.
55

56
```typescript { .api }
57
/**
58
 * WeakMap storing references to all SimpleBar instances
59
 * Key: DOM element, Value: SimpleBar instance
60
 */
61
static instances: WeakMap<Node, SimpleBar>;
62
```
63

64
**Usage Examples:**
65

66
```typescript
67
// Get existing instance from element
68
const element = document.querySelector('[data-simplebar]');
69
const instance = SimpleBar.instances.get(element);
70

71
if (instance) {
72
  // Use existing instance
73
  instance.recalculate();
74
  
75
  // Access scroll element
76
  const scrollEl = instance.getScrollElement();
77
  scrollEl.scrollTop = 100;
78
}
79
```
80

81
### Global Observer Management
82

83
Controls the global DOM mutation observer for automatic element detection.
84

85
```typescript { .api }
86
/**
87
 * Global MutationObserver that watches for new elements with data-simplebar
88
 */
89
static globalObserver: MutationObserver;
90

91
/**
92
 * Disconnect the global MutationObserver
93
 * Use when you no longer need automatic detection of new elements
94
 */
95
static removeObserver(): void;
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
// Disable automatic detection of new elements
102
SimpleBar.removeObserver();
103

104
// All existing instances continue to work
105
// But new elements with data-simplebar won't be automatically initialized
106
```
107

108
### Mutation Handling
109

110
Handles DOM changes to automatically initialize or cleanup SimpleBar instances.
111

112
```typescript { .api }
113
/**
114
 * Handles DOM mutations to initialize new elements or cleanup removed ones
115
 * @param mutations - Array of MutationRecord objects from MutationObserver
116
 */
117
static handleMutations(mutations: MutationRecord[]): void;
118
```
119

120
## Data Attribute Configuration
121

122
Configure SimpleBar options using HTML data attributes:
123

124
```html
125
<!-- Auto-hide behavior -->
126
<div data-simplebar data-simplebar-auto-hide="false">Content</div>
127

128
<!-- Scrollbar sizing -->
129
<div data-simplebar 
130
     data-simplebar-scrollbar-min-size="20"
131
     data-simplebar-scrollbar-max-size="100">Content</div>
132

133
<!-- Track click behavior -->
134
<div data-simplebar data-simplebar-click-on-track="false">Content</div>
135

136
<!-- Force visibility -->
137
<div data-simplebar data-simplebar-force-visible="true">Content</div>
138
<div data-simplebar data-simplebar-force-visible="y">Content</div>
139

140
<!-- Accessibility -->
141
<div data-simplebar 
142
     data-simplebar-aria-label="Chat messages"
143
     data-simplebar-tab-index="1">Content</div>
144
```
145

146
## Browser Compatibility
147

148
The HTML API requires:
149

150
- **MutationObserver**: Supported in all modern browsers, IE11+
151
- **ResizeObserver**: May require polyfill for IE/Safari
152
- **CSS Custom Properties**: For advanced styling (optional)
153

154
For IE10 support, disable automatic initialization and use manual initialization only:
155

156
```typescript
157
// Disable automatic initialization
158
SimpleBar.removeObserver();
159

160
// Manual initialization for IE10
161
document.querySelectorAll('[data-simplebar]').forEach(el => {
162
  new SimpleBar(el);
163
});
164
```