0
# Tether
1

2
Tether is a client-side JavaScript library for precise positioning of UI elements relative to each other on web pages. It solves complex positioning challenges that arise when DOM tree placement becomes problematic, such as handling fixed-positioned elements, scrollable containers, and viewport clipping issues.
3

4
## Package Information
5

6
- **Package Name**: tether
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install tether`
10

11
## Core Imports
12

13
```javascript
14
import Tether from "tether";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const Tether = require("tether");
21
```
22

23
For UMD/browser:
24

25
```html
26
<script src="path/to/tether.min.js"></script>
27
```
28

29
## Basic Usage
30

31
```javascript
32
import Tether from "tether";
33

34
// Create a new tether instance
35
const tether = new Tether({
36
  element: '.tooltip',        // Element to be positioned
37
  target: '.button',          // Element to attach to
38
  attachment: 'top center',   // Attachment point on element
39
  targetAttachment: 'bottom center'  // Attachment point on target
40
});
41

42
// Enable positioning
43
tether.enable();
44

45
// Later, disable and clean up
46
tether.disable();
47
tether.destroy();
48
```
49

50
## Architecture
51

52
Tether is built around several key components:
53

54
- **Core Tether Class**: Main positioning engine with lifecycle management
55
- **Event System**: Built-in event handling via Evented base class
56
- **Positioning Modules**: Pluggable modules (Constraint, Abutment, Shift) for advanced positioning logic
57
- **Attachment System**: Flexible attachment point specification with automatic fallbacks
58
- **CSS Class Management**: Automatic CSS class application for styling positioned elements
59
- **Performance Optimization**: Caching and optimized repositioning for smooth interactions
60

61
## Capabilities
62

63
### Core Positioning
64

65
Essential positioning functionality for attaching elements to targets with precise control over attachment points and offsets.
66

67
```javascript { .api }
68
class Tether {
69
  constructor(options: TetherOptions);
70
}
71

72
interface TetherOptions {
73
  element: string | HTMLElement;
74
  target: string | HTMLElement;
75
  attachment: string;
76
  targetAttachment?: string;
77
  offset?: string;
78
  targetOffset?: string;
79
  enabled?: boolean;
80
  classPrefix?: string;
81
  bodyElement?: HTMLElement;
82
}
83
```
84

85
[Core Positioning](./core-positioning.md)
86

87
### Event System
88

89
Event handling system for responding to positioning changes and tether lifecycle events.
90

91
```javascript { .api }
92
// Event methods inherited from Evented base class
93
on(event: string, handler: Function, ctx?: any, once?: boolean): Tether;
94
once(event: string, handler: Function, ctx?: any): Tether;
95
off(event?: string, handler?: Function): Tether;
96
trigger(event: string, ...args: any[]): Tether;
97
```
98

99
[Event System](./event-system.md)
100

101
### Constraints and Boundaries
102

103
Advanced positioning constraints to keep elements within specified boundaries and handle viewport clipping.
104

105
```javascript { .api }
106
interface ConstraintOptions {
107
  to: string | HTMLElement | Array<number>;
108
  attachment?: string;
109
  pin?: boolean | string | Array<string>;
110
  outOfBoundsClass?: string;
111
  pinnedClass?: string;
112
}
113
```
114

115
[Constraints](./constraints.md)
116

117
### Optimization and Performance
118

119
Performance optimizations and positioning strategies for smooth user experiences.
120

121
```javascript { .api }
122
interface OptimizationOptions {
123
  moveElement?: boolean;
124
  allowPositionFixed?: boolean;
125
  gpu?: boolean;
126
}
127
```
128

129
[Optimization](./optimization.md)
130

131
### Static Properties and Methods
132

133
Global Tether functionality and module system.
134

135
```javascript { .api }
136
// Static properties
137
static modules: Array<PositioningModule>;
138

139
// Static methods
140
static position(): void;
141
```
142

143
## Types
144

145
```javascript { .api }
146
// Attachment point values
147
type AttachmentPoint = 
148
  | "top left" | "top center" | "top right"
149
  | "middle left" | "middle center" | "middle right" 
150
  | "bottom left" | "bottom center" | "bottom right"
151
  | "auto auto";
152

153
// Target modifier values
154
type TargetModifier = "visible" | "scroll-handle";
155

156
// Event names
157
type TetherEvents = "update" | "repositioned";
158

159
// Positioning module interface
160
interface PositioningModule {
161
  initialize?: () => void;
162
  position: (positionData: PositionData) => boolean | PositionCoordinates | void;
163
}
164

165
interface PositionData {
166
  left: number;
167
  top: number;
168
  targetAttachment: AttachmentConfig;
169
  targetPos: BoundsObject;
170
  elementPos: BoundsObject;
171
  offset: OffsetObject;
172
  targetOffset: OffsetObject;
173
  manualOffset: OffsetObject;
174
  manualTargetOffset: OffsetObject;
175
  scrollbarSize: { width: number; height: number };
176
  attachment: AttachmentConfig;
177
}
178

179
interface PositionCoordinates {
180
  top: number;
181
  left: number;
182
}
183
```
184

185
## CSS Classes
186

187
Tether automatically applies CSS classes to positioned elements and targets based on their state and positioning. All classes can be customized using the `classPrefix` option (default: 'tether') or overridden entirely with the `classes` option.
188

189
### Core Classes
190

191
```javascript { .api }
192
// Basic element classes
193
".tether-element"          // Applied to the positioned element
194
".tether-target"           // Applied to the target element  
195
".tether-enabled"          // Applied when tether is enabled
196

197
// Attachment classes (applied to both element and target)
198
".tether-element-attached-{side}"  // Element attachment side
199
".tether-target-attached-{side}"   // Target attachment side
200

201
// Where {side} can be: top, bottom, left, right, middle, center
202
```
203

204
### State Classes
205

206
```javascript { .api }
207
// Constraint-related classes
208
".tether-out-of-bounds"           // Element is outside boundaries
209
".tether-out-of-bounds-{side}"    // Specific boundary violation
210
".tether-pinned"                  // Element has been pinned
211
".tether-pinned-{side}"           // Pinned to specific side
212

213
// Abutment classes (when using Abutment module)
214
".tether-abutted"                 // Element is abutting boundaries
215
".tether-abutted-{side}"          // Abutting specific side
216

217
// Where {side} can be: top, bottom, left, right
218
```
219

220
### Debug/Development Classes
221

222
```javascript { .api }
223
// Marker classes (for visual debugging)
224
".tether-element-marker"          // Visual marker on positioned element
225
".tether-target-marker"           // Visual marker on target element  
226
".tether-marker-dot"              // Dot within markers showing offset points
227
```
228

229
### Class Customization
230

231
Override default classes using the `classes` option:
232

233
```javascript
234
const tether = new Tether({
235
  element: '.tooltip',
236
  target: '.button',
237
  attachment: 'top center',
238
  targetAttachment: 'bottom center',
239
  classes: {
240
    'element': 'my-tooltip',           // Instead of .tether-element
241
    'target': 'my-trigger',            // Instead of .tether-target
242
    'enabled': false,                  // Disable .tether-enabled class
243
    'out-of-bounds': 'tooltip-hidden'  // Custom out-of-bounds class
244
  }
245
});
246
```