0
# Positioning and Alignment
1

2
Advanced popup positioning system with precise alignment configuration, overflow handling, and built-in placement presets. The positioning system integrates with rc-align to provide flexible and intelligent popup placement.
3

4
## Capabilities
5

6
### Alignment Configuration
7

8
Core alignment interface for controlling popup positioning relative to the trigger element.
9

10
```typescript { .api }
11
/**
12
 * Alignment configuration for popup positioning
13
 */
14
interface AlignType {
15
  /** 
16
   * Alignment points between source and target nodes
17
   * Format: ['sourcePoint', 'targetPoint'] where points are combinations of:
18
   * - 't' (top), 'b' (bottom), 'c' (center) for vertical
19
   * - 'l' (left), 'r' (right), 'c' (center) for horizontal
20
   * Example: ['tr', 'bl'] aligns top-right of popup with bottom-left of trigger
21
   */
22
  points?: AlignPoint[];
23
  
24
  /** 
25
   * Offset popup by [x, y] pixels from aligned position
26
   * Supports percentage strings relative to popup size
27
   */
28
  offset?: number[];
29
  
30
  /** 
31
   * Offset target by [x, y] pixels before alignment
32
   * Supports percentage strings relative to target size
33
   */
34
  targetOffset?: number[];
35
  
36
  /** Overflow adjustment configuration */
37
  overflow?: {
38
    /** Auto-adjust horizontally if popup overflows viewport */
39
    adjustX?: boolean | number;
40
    /** Auto-adjust vertically if popup overflows viewport */
41
    adjustY?: boolean | number;
42
  };
43
  
44
  /** Use CSS right property instead of left for positioning */
45
  useCssRight?: boolean;
46
  
47
  /** Use CSS bottom property instead of top for positioning */
48
  useCssBottom?: boolean;
49
  
50
  /** Use CSS transform for positioning (better performance) */
51
  useCssTransform?: boolean;
52
  
53
  /** Ignore small position adjustments to prevent shake */
54
  ignoreShake?: boolean;
55
}
56

57
type AlignPoint = string; // Two-character combinations like 'tl', 'tr', 'bl', 'br', 'cc', 'tc', 'bc', 'cl', 'cr'
58
```
59

60
### Built-in Placements
61

62
Predefined placement configurations for common positioning scenarios.
63

64
```typescript { .api }
65
/**
66
 * Built-in placement configurations mapping placement names to alignment configs
67
 */
68
type BuildInPlacements = Record<string, AlignType>;
69

70
interface TriggerProps {
71
  /** Popup alignment configuration */
72
  popupAlign?: AlignType;
73
  
74
  /** Placement key from builtinPlacements */
75
  popupPlacement?: string;
76
  
77
  /** Predefined placement configurations */
78
  builtinPlacements?: BuildInPlacements;
79
  
80
  /** Generate CSS class name from alignment result */
81
  getPopupClassNameFromAlign?: (align: AlignType) => string;
82
  
83
  /** Callback when popup alignment completes */
84
  onPopupAlign?: (element: HTMLElement, align: AlignType) => void;
85
}
86
```
87

88
### Point Alignment
89

90
Align popup to mouse cursor position for context menus and tooltips.
91

92
```typescript { .api }
93
interface TriggerProps {
94
  /** Whether to align popup to mouse point instead of trigger element */
95
  alignPoint?: boolean;
96
}
97

98
interface Point {
99
  pageX: number;
100
  pageY: number;
101
}
102

103
interface TriggerState {
104
  /** Current mouse point for alignment */
105
  point?: Point;
106
}
107
```
108

109
**Usage Examples:**
110

111
```typescript
112
import React from "react";
113
import Trigger from "rc-trigger";
114

115
// Basic alignment with offset
116
function BasicAlignment() {
117
  return (
118
    <Trigger
119
      action={['click']}
120
      popup={<div>Popup content</div>}
121
      popupAlign={{
122
        points: ['tl', 'bl'], // Popup top-left to trigger bottom-left
123
        offset: [0, 4], // 4px gap below trigger
124
        overflow: { adjustX: true, adjustY: true }
125
      }}
126
    >
127
      <button>Click me</button>
128
    </Trigger>
129
  );
130
}
131

132
// Built-in placements
133
function BuiltinPlacements() {
134
  const placements = {
135
    topLeft: {
136
      points: ['bl', 'tl'],
137
      offset: [0, -4],
138
      overflow: { adjustX: true, adjustY: true }
139
    },
140
    topRight: {
141
      points: ['br', 'tr'],
142
      offset: [0, -4],
143
      overflow: { adjustX: true, adjustY: true }
144
    },
145
    bottomLeft: {
146
      points: ['tl', 'bl'],
147
      offset: [0, 4],
148
      overflow: { adjustX: true, adjustY: true }
149
    },
150
    bottomRight: {
151
      points: ['tr', 'br'],
152
      offset: [0, 4],
153
      overflow: { adjustX: true, adjustY: true }
154
    }
155
  };
156

157
  return (
158
    <Trigger
159
      action={['click']}
160
      popup={<div>Popup with built-in placement</div>}
161
      popupPlacement="bottomLeft"
162
      builtinPlacements={placements}
163
    >
164
      <button>Click me</button>
165
    </Trigger>
166
  );
167
}
168

169
// Point alignment for context menu
170
function ContextMenu() {
171
  return (
172
    <Trigger
173
      action={['contextMenu']}
174
      popup={
175
        <ul style={{ margin: 0, padding: 8, listStyle: 'none', background: 'white', boxShadow: '0 2px 8px rgba(0,0,0,0.1)' }}>
176
          <li>Menu Item 1</li>
177
          <li>Menu Item 2</li>
178
          <li>Menu Item 3</li>
179
        </ul>
180
      }
181
      alignPoint={true}
182
      popupAlign={{
183
        points: ['tl', 'tl'],
184
        overflow: { adjustX: true, adjustY: true }
185
      }}
186
    >
187
      <div style={{ padding: 20, background: '#f0f0f0' }}>
188
        Right-click for context menu
189
      </div>
190
    </Trigger>
191
  );
192
}
193

194
// Advanced alignment with CSS positioning
195
function AdvancedAlignment() {
196
  return (
197
    <Trigger
198
      action={['click']}
199
      popup={<div>Positioned with CSS transform</div>}
200
      popupAlign={{
201
        points: ['cc', 'cc'], // Center to center
202
        useCssTransform: true, // Use transform for better performance
203
        ignoreShake: true // Prevent micro-adjustments
204
      }}
205
    >
206
      <button>Center-aligned popup</button>
207
    </Trigger>
208
  );
209
}
210

211
// Dynamic class name from alignment
212
function DynamicClassName() {
213
  const getClassName = (align) => {
214
    const points = align.points || [];
215
    return `popup-${points[0]}-${points[1]}`;
216
  };
217

218
  return (
219
    <Trigger
220
      action={['hover']}
221
      popup={<div>Popup with dynamic class</div>}
222
      popupAlign={{
223
        points: ['tc', 'bc'],
224
        offset: [0, -4]
225
      }}
226
      getPopupClassNameFromAlign={getClassName}
227
      onPopupAlign={(element, align) => {
228
        console.log('Popup aligned:', align);
229
      }}
230
    >
231
      <button>Hover for popup</button>
232
    </Trigger>
233
  );
234
}
235
```
236

237
## Common Alignment Patterns
238

239
### Dropdown Menu
240
```typescript
241
popupAlign={{
242
  points: ['tl', 'bl'],
243
  offset: [0, 4],
244
  overflow: { adjustX: true, adjustY: true }
245
}}
246
```
247

248
### Tooltip Above
249
```typescript
250
popupAlign={{
251
  points: ['bc', 'tc'],
252
  offset: [0, -8],
253
  overflow: { adjustX: true, adjustY: true }
254
}}
255
```
256

257
### Tooltip Below
258
```typescript
259
popupAlign={{
260
  points: ['tc', 'bc'],
261
  offset: [0, 8],
262
  overflow: { adjustX: true, adjustY: true }
263
}}
264
```
265

266
### Side Panel
267
```typescript
268
popupAlign={{
269
  points: ['tl', 'tr'],
270
  offset: [4, 0],
271
  overflow: { adjustX: true, adjustY: true }
272
}}
273
```
274

275
### Centered Modal
276
```typescript
277
popupAlign={{
278
  points: ['cc', 'cc'],
279
  useCssTransform: true
280
}}
281
```