0
# Optimization and Performance
1

2
Performance optimizations and positioning strategies for smooth user experiences. Tether provides various optimization options to improve rendering performance and reduce layout thrashing.
3

4
## Capabilities
5

6
### Optimization Configuration
7

8
Configure performance optimizations for better positioning performance.
9

10
```javascript { .api }
11
interface OptimizationOptions {
12
  /** Whether to move elements to optimize positioning (defaults to true) */
13
  moveElement?: boolean;
14
  /** Whether to allow position: fixed for better performance (defaults to true) */
15
  allowPositionFixed?: boolean;
16
  /** Whether to use GPU acceleration via transforms (defaults to true unless false) */
17
  gpu?: boolean;
18
}
19
```
20

21
**Usage in Tether Options:**
22

23
```javascript
24
import Tether from "tether";
25

26
const tether = new Tether({
27
  element: '.tooltip',
28
  target: '.button',
29
  attachment: 'top center',
30
  targetAttachment: 'bottom center',
31
  optimizations: {
32
    moveElement: true,
33
    allowPositionFixed: true,
34
    gpu: true
35
  }
36
});
37
```
38

39
### GPU Acceleration
40

41
Control GPU acceleration through CSS transforms for better performance.
42

43
```javascript { .api }
44
/**
45
 * GPU acceleration options
46
 * - true (default): Use transforms with GPU acceleration
47
 * - false: Use traditional top/left positioning
48
 */
49
gpu?: boolean;
50
```
51

52
**Performance Impact:**
53

54
- **GPU enabled**: Uses `transform: translateX() translateY() translateZ(0)` for hardware acceleration
55
- **GPU disabled**: Uses `top` and `left` CSS properties for positioning
56
- **Automatic device pixel ratio handling**: Rounds transform values to avoid blurry rendering
57

58
**Usage Examples:**
59

60
```javascript
61
// Enable GPU acceleration (default)
62
{
63
  optimizations: {
64
    gpu: true
65
  }
66
}
67

68
// Disable GPU acceleration for compatibility
69
{
70
  optimizations: {
71
    gpu: false
72
  }
73
}
74
```
75

76
### Position Strategy
77

78
Control CSS positioning strategy for optimal performance.
79

80
```javascript { .api }
81
/**
82
 * Position strategy options
83
 * - allowPositionFixed: true - Use position: fixed when beneficial
84
 * - allowPositionFixed: false - Always use position: absolute
85
 */
86
allowPositionFixed?: boolean;
87
```
88

89
**Positioning Strategies:**
90

91
1. **Fixed positioning**: When element and target are both in viewport
92
2. **Absolute positioning**: When using offset parent optimization
93
3. **Fallback absolute positioning**: When other strategies don't apply
94

95
**Usage Examples:**
96

97
```javascript
98
// Allow fixed positioning (default - better performance)
99
{
100
  optimizations: {
101
    allowPositionFixed: true
102
  }
103
}
104

105
// Force absolute positioning (compatibility mode)
106
{
107
  optimizations: {
108
    allowPositionFixed: false
109
  }
110
}
111
```
112

113
### Element Movement Optimization
114

115
Control whether Tether can move elements in the DOM for better positioning.
116

117
```javascript { .api }
118
/**
119
 * Element movement options
120
 * - moveElement: true - Allow moving element to optimize positioning
121
 * - moveElement: false - Keep element in original DOM location
122
 */
123
moveElement?: boolean;
124
```
125

126
**Movement Behaviors:**
127

128
- **When enabled**: Tether may move the element to a better offset parent for more efficient positioning
129
- **When disabled**: Element stays in its original DOM location, may impact performance
130
- **Automatic detection**: Tether determines optimal offset parent based on target element
131

132
**Usage Examples:**
133

134
```javascript
135
// Allow element movement (default - better performance)
136
{
137
  optimizations: {
138
    moveElement: true
139
  }
140
}
141

142
// Prevent element movement (preserve DOM structure)
143
{
144
  optimizations: {
145
    moveElement: false
146
  }
147
}
148
```
149

150
## Performance Features
151

152
### Automatic Caching
153

154
Tether automatically caches expensive computations for better performance.
155

156
```javascript { .api }
157
/**
158
 * Internal caching system (automatic)
159
 * Caches: element bounds, target bounds, offset parent info, scrollbar size
160
 */
161
cache(key: string, getter: Function): any;
162
clearCache(): void;
163
```
164

165
**Cached Values:**
166
- Element bounding rectangles
167
- Target bounding rectangles  
168
- Offset parent calculations
169
- Scrollbar size measurements
170
- Transform key detection
171

172
### Throttled Positioning
173

174
Built-in throttling prevents excessive positioning calls.
175

176
**Throttling Features:**
177
- **Frame rate limiting**: Voluntary throttling when performance drops below 60fps
178
- **Event debouncing**: Prevents rapid-fire positioning calls
179
- **Minimum interval**: 10ms minimum between position calculations
180

181
### Batch Updates
182

183
Deferred DOM updates reduce layout thrashing.
184

185
```javascript { .api }
186
/**
187
 * Deferred update system (internal)
188
 * Batches CSS changes and class updates for better performance
189
 */
190
defer(callback: Function): void;
191
flush(): void;
192
```
193

194
**Benefits:**
195
- Groups multiple DOM changes into single reflow
196
- Reduces layout thrashing during complex positioning
197
- Improves performance with multiple active tethers
198

199
## Global Performance Controls
200

201
### Global Positioning
202

203
Control all active tethers simultaneously.
204

205
```javascript { .api }
206
/**
207
 * Global positioning function for all active tethers
208
 * Efficiently updates all tether instances at once
209
 */
210
Tether.position(): void;
211
```
212

213
**Usage Example:**
214

215
```javascript
216
// Manually trigger positioning for all tethers
217
Tether.position();
218

219
// Useful after significant DOM changes
220
document.addEventListener('orientationchange', () => {
221
  setTimeout(Tether.position, 100);
222
});
223
```
224

225
### Automatic Event Handling
226

227
Built-in event listeners for automatic repositioning.
228

229
**Auto-handled Events:**
230
- `window.resize` - Viewport size changes
231
- `window.scroll` - Window scrolling
232
- `touchmove` - Touch-based scrolling
233
- Element scroll events - For scroll parents
234

235
## Performance Best Practices
236

237
### Efficient Configuration
238

239
```javascript
240
// Optimal configuration for performance
241
const tether = new Tether({
242
  element: '.element',
243
  target: '.target',
244
  attachment: 'top center',
245
  targetAttachment: 'bottom center',
246
  
247
  // Performance optimizations
248
  optimizations: {
249
    moveElement: true,        // Allow DOM restructuring
250
    allowPositionFixed: true, // Use fixed positioning when possible
251
    gpu: true                 // Enable hardware acceleration
252
  },
253
  
254
  // Efficient class management
255
  classPrefix: 'tether',      // Use short prefixes
256
  addTargetClasses: false     // Skip target classes if not needed
257
});
258
```
259

260
### Memory Management
261

262
```javascript
263
// Proper cleanup to prevent memory leaks
264
class MyComponent {
265
  constructor() {
266
    this.tether = new Tether({
267
      element: '.my-element',
268
      target: '.my-target',
269
      attachment: 'top center',
270
      targetAttachment: 'bottom center'
271
    });
272
  }
273
  
274
  destroy() {
275
    // Always destroy tether instances
276
    this.tether.destroy();
277
    this.tether = null;
278
  }
279
}
280
```
281

282
### Multiple Tethers
283

284
```javascript
285
// Efficient management of multiple tethers
286
class MultiTether {
287
  constructor() {
288
    this.tethers = [];
289
  }
290
  
291
  addTether(options) {
292
    const tether = new Tether(options);
293
    this.tethers.push(tether);
294
    return tether;
295
  }
296
  
297
  updateAll() {
298
    // Use global positioning for efficiency
299
    Tether.position();
300
  }
301
  
302
  destroy() {
303
    // Clean up all tethers
304
    this.tethers.forEach(tether => tether.destroy());
305
    this.tethers = [];
306
  }
307
}
308
```
309

310
## Performance Monitoring
311

312
### Custom Performance Tracking
313

314
```javascript
315
// Monitor positioning performance
316
const tether = new Tether({
317
  element: '.element',
318
  target: '.target',
319
  attachment: 'top center',
320
  targetAttachment: 'bottom center'
321
});
322

323
tether.on('repositioned', function() {
324
  // Track positioning frequency
325
  console.time('reposition-time');
326
  requestAnimationFrame(() => {
327
    console.timeEnd('reposition-time');
328
  });
329
});
330
```
331

332
### Debug Information
333

334
```javascript
335
// Access internal positioning data for debugging
336
tether.on('repositioned', function() {
337
  // Check positioning history
338
  console.log('Position history:', this.history);
339
  
340
  // Check cache status
341
  console.log('Cache keys:', Object.keys(this._cache || {}));
342
});
343
```