0
# Core Positioning
1

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

4
## Capabilities
5

6
### Constructor
7

8
Creates a new Tether instance with the specified configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Tether instance for positioning an element relative to a target
13
 * @param options - Configuration object for the tether
14
 */
15
constructor(options: TetherOptions);
16

17
interface TetherOptions {
18
  /** Element to be positioned (CSS selector or DOM element) */
19
  element: string | HTMLElement;
20
  /** Target element to attach to (CSS selector or DOM element) */
21
  target: string | HTMLElement;
22
  /** Attachment point on the element being positioned */
23
  attachment: string;
24
  /** Attachment point on the target element (defaults to 'auto auto') */
25
  targetAttachment?: string;
26
  /** Offset from the attachment point (defaults to '0 0') */
27
  offset?: string;
28
  /** Offset from the target attachment point (defaults to '0 0') */
29
  targetOffset?: string;
30
  /** Whether the tether is initially enabled (defaults to true) */
31
  enabled?: boolean;
32
  /** Prefix for generated CSS classes (defaults to 'tether') */
33
  classPrefix?: string;
34
  /** Element to append the positioned element to (defaults to document.body) */
35
  bodyElement?: HTMLElement | string;
36
  /** Array of constraint objects for boundary checking */
37
  constraints?: ConstraintOptions[];
38
  /** Performance and positioning optimizations */
39
  optimizations?: OptimizationOptions;
40
  /** Whether to add classes to the target element (defaults to true) */
41
  addTargetClasses?: boolean;
42
  /** Target modifier for special target behaviors */
43
  targetModifier?: string;
44
  /** Manual positioning shift options */
45
  shift?: string | ShiftOptions | Function;
46
  /** Custom CSS class overrides for specific element states */
47
  classes?: {
48
    [key: string]: string | false;
49
  };
50
}
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
import Tether from "tether";
57

58
// Basic positioning
59
const tether = new Tether({
60
  element: '#tooltip',
61
  target: '#button',
62
  attachment: 'top center',
63
  targetAttachment: 'bottom center'
64
});
65

66
// With offsets and custom classes
67
const advancedTether = new Tether({
68
  element: document.querySelector('.dropdown'),
69
  target: '.trigger',
70
  attachment: 'top left',
71
  targetAttachment: 'bottom left',
72
  offset: '0 10px',
73
  classPrefix: 'my-tether',
74
  bodyElement: document.querySelector('.container')
75
});
76

77
// With manual shift adjustment
78
const shiftedTether = new Tether({
79
  element: '.popover',
80
  target: '.anchor',
81
  attachment: 'top center',
82
  targetAttachment: 'bottom center',
83
  shift: '10px 5px'  // Shift position by 10px down, 5px right
84
});
85

86
// With dynamic shift function
87
const dynamicTether = new Tether({
88
  element: '.tooltip',
89
  target: '.help-icon',
90
  attachment: 'top center',
91
  targetAttachment: 'bottom center',
92
  shift: function(pos) {
93
    // Custom shift logic based on current position
94
    return { top: pos.top - 5, left: pos.left + 10 };
95
  }
96
});
97
```
98

99
### Position Method
100

101
Calculates and applies positioning for the tethered element.
102

103
```javascript { .api }
104
/**
105
 * Calculates and applies positioning for the tethered element
106
 * @param flushChanges - Whether to immediately apply changes (defaults to true)
107
 * @returns Boolean indicating if positioning was successful
108
 */
109
position(flushChanges?: boolean): boolean;
110
```
111

112
### Enable Method
113

114
Enables the tether and starts positioning.
115

116
```javascript { .api }
117
/**
118
 * Enables the tether and starts positioning
119
 * @param pos - Whether to position immediately after enabling (defaults to true)
120
 */
121
enable(pos?: boolean): void;
122
```
123

124
### Disable Method
125

126
Disables tether positioning and removes event listeners.
127

128
```javascript { .api }
129
/**
130
 * Disables tether positioning and removes event listeners
131
 */
132
disable(): void;
133
```
134

135
### Destroy Method
136

137
Completely destroys the tether instance, removing all classes and event listeners.
138

139
```javascript { .api }
140
/**
141
 * Completely destroys the tether instance
142
 * Removes all applied classes and cleans up event listeners
143
 */
144
destroy(): void;
145
```
146

147
### Set Options Method
148

149
Updates tether configuration options.
150

151
```javascript { .api }
152
/**
153
 * Updates tether configuration options
154
 * @param options - New options to merge with existing configuration
155
 * @param pos - Whether to reposition after setting options (defaults to true)
156
 */
157
setOptions(options: Partial<TetherOptions>, pos?: boolean): void;
158
```
159

160
**Usage Example:**
161

162
```javascript
163
// Update attachment points dynamically
164
tether.setOptions({
165
  attachment: 'bottom center',
166
  targetAttachment: 'top center',
167
  offset: '5px 0'
168
});
169
```
170

171
### Utility Methods
172

173
Helper methods for advanced positioning control.
174

175
```javascript { .api }
176
/**
177
 * Gets the bounding rectangle of the target element
178
 * Considers target modifiers like 'visible' and 'scroll-handle'
179
 * @returns Bounds object with position and dimensions
180
 */
181
getTargetBounds(): BoundsObject;
182

183
/**
184
 * Clears the internal positioning cache
185
 * Useful when DOM has changed and cache needs refreshing
186
 */
187
clearCache(): void;
188

189
/**
190
 * Caches computed values for performance optimization
191
 * @param key - Cache key
192
 * @param getter - Function to compute the cached value
193
 * @returns Cached or computed value
194
 */
195
cache(key: string, getter: Function): any;
196

197
/**
198
 * Updates CSS classes based on current attachment points
199
 * @param elementAttach - Element attachment configuration
200
 * @param targetAttach - Target attachment configuration
201
 */
202
updateAttachClasses(elementAttach?: AttachmentConfig, targetAttach?: AttachmentConfig): void;
203

204
/**
205
 * Moves the element to the specified position with optimization handling
206
 * Internal method that applies calculated positioning with performance optimizations
207
 * @param pos - Position data containing page, viewport, and offset coordinates
208
 */
209
move(pos: PositionData): void;
210
```
211

212
## Types
213

214
```javascript { .api }
215
interface BoundsObject {
216
  top: number;
217
  left: number;
218
  right: number;
219
  bottom: number;
220
  width: number;
221
  height: number;
222
}
223

224
interface AttachmentConfig {
225
  top: string | false;
226
  left: string | false;
227
}
228

229
interface ShiftOptions {
230
  top: number;
231
  left: number;
232
}
233

234
interface OffsetObject {
235
  top: number;
236
  left: number;
237
}
238

239
interface PositionData {
240
  page: {
241
    top: number;
242
    left: number;
243
    bottom?: number;
244
    right?: number;
245
  };
246
  viewport: {
247
    top: number;
248
    left: number;
249
    bottom: number;
250
    right: number;
251
  };
252
  offset?: {
253
    top: number;
254
    left: number;
255
  };
256
}
257
```