0
# Popper.js Core
1

2
Popper.js Core is a lightweight (~3 kB) tooltip and popover positioning engine that automatically calculates optimal placement for UI elements. It provides advanced positioning logic with automatic flip detection, overflow prevention, and virtual positioning capabilities that pure CSS solutions cannot achieve.
3

4
## Package Information
5

6
- **Package Name**: @popperjs/core
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install @popperjs/core`
10

11
## Core Imports
12

13
```javascript
14
import { createPopper } from '@popperjs/core';
15
```
16

17
For specific modifiers or lite version:
18

19
```javascript
20
import { createPopperLite, flip, preventOverflow } from '@popperjs/core';
21
```
22

23
For constants and advanced use:
24

25
```javascript
26
import { createPopper, top, bottom, placements, modifierPhases } from '@popperjs/core';
27
```
28

29
CommonJS:
30

31
```javascript
32
const { createPopper } = require('@popperjs/core');
33
```
34

35
UMD (via CDN):
36

37
```html
38
<script src="https://unpkg.com/@popperjs/core@2"></script>
39
<!-- Access via Popper.createPopper -->
40
```
41

42
## Basic Usage
43

44
```javascript
45
import { createPopper } from '@popperjs/core';
46

47
const button = document.querySelector('#button');
48
const tooltip = document.querySelector('#tooltip');
49

50
// Create popper instance
51
const popperInstance = createPopper(button, tooltip, {
52
  placement: 'top',
53
  modifiers: [
54
    {
55
      name: 'offset',
56
      options: {
57
        offset: [0, 8],
58
      },
59
    },
60
  ],
61
});
62

63
// Update positioning
64
popperInstance.update();
65

66
// Cleanup when done
67
popperInstance.destroy();
68
```
69

70
## Architecture
71

72
Popper.js is built around several key components:
73

74
- **createPopper Functions**: Three variants (full, lite, base) that create popper instances
75
- **Modifier System**: Extensible plugins that control positioning behavior during update cycles
76
- **State Management**: Centralized state object containing positioning data and element references
77
- **Event Handling**: Automatic scroll/resize event management with debounced updates
78
- **Virtual Elements**: Support for positioning relative to mouse coordinates or abstract points
79

80
## Capabilities
81

82
### Core Positioning
83

84
Main createPopper function and instance management for tooltip and popover positioning.
85

86
```javascript { .api }
87
function createPopper(
88
  reference: Element | VirtualElement,
89
  popper: HTMLElement,
90
  options?: Partial<Options>
91
): Instance;
92

93
interface Instance {
94
  state: State;
95
  destroy(): void;
96
  forceUpdate(): void;
97
  update(): Promise<Partial<State>>;
98
  setOptions(setOptionsAction: SetAction<Partial<Options>>): Promise<Partial<State>>;
99
}
100
```
101

102
[Core Positioning](./core-positioning.md)
103

104
### Built-in Modifiers
105

106
Nine built-in modifiers that control positioning behavior including flip, preventOverflow, offset, arrow, and more.
107

108
```javascript { .api }
109
// Key modifiers for positioning control
110
const flip: Modifier<'flip', FlipOptions>;
111
const preventOverflow: Modifier<'preventOverflow', PreventOverflowOptions>;
112
const offset: Modifier<'offset', OffsetOptions>;
113
const arrow: Modifier<'arrow', ArrowOptions>;
114
```
115

116
[Built-in Modifiers](./built-in-modifiers.md)
117

118
### Variants and Tree-shaking
119

120
Three different builds for various bundle size requirements and tree-shaking optimization.
121

122
```javascript { .api }
123
// Full version with all modifiers
124
function createPopper(reference, popper, options?): Instance;
125

126
// Lite version with minimal modifiers
127
function createPopperLite(reference, popper, options?): Instance;
128

129
// Base version with no default modifiers
130
function createPopperBase(reference, popper, options?): Instance;
131

132
// Factory function for custom builds
133
function popperGenerator(generatorOptions?): typeof createPopper;
134
```
135

136
[Variants and Tree-shaking](./variants-tree-shaking.md)
137

138
### Virtual Elements
139

140
Support for positioning relative to virtual coordinates for context menus and mouse-following tooltips.
141

142
```javascript { .api }
143
interface VirtualElement {
144
  getBoundingClientRect(): ClientRect | DOMRect;
145
  contextElement?: Element;
146
}
147
```
148

149
[Virtual Elements](./virtual-elements.md)
150

151
### Utility Functions
152

153
Core utility functions for advanced use cases and custom modifier development.
154

155
```javascript { .api }
156
// Detect overflow conditions for positioning logic
157
function detectOverflow(
158
  state: State,
159
  options?: {
160
    boundary?: Boundary;
161
    rootBoundary?: RootBoundary;
162
    padding?: Padding;
163
    altBoundary?: boolean;
164
  }
165
): SideObject;
166

167
type SideObject = {
168
  top: number;
169
  right: number;
170
  bottom: number;
171
  left: number;
172
};
173
```
174

175
### Constants and Enums
176

177
Useful constants for advanced positioning logic and custom modifier development.
178

179
```javascript { .api }
180
// Placement constants
181
const placements: Array<Placement>;
182
const basePlacements: Array<BasePlacement>;
183
const variationPlacements: Array<VariationPlacement>;
184

185
// Direction constants
186
const top: 'top';
187
const bottom: 'bottom';
188
const left: 'left';
189
const right: 'right';
190
const start: 'start';
191
const end: 'end';
192
const auto: 'auto';
193

194
// Boundary constants
195
const clippingParents: 'clippingParents';
196
const viewport: 'viewport';
197

198
// Context constants  
199
const popper: 'popper';
200
const reference: 'reference';
201

202
// Modifier execution phases
203
const modifierPhases: Array<ModifierPhases>;
204
```
205

206
## Types
207

208
```javascript { .api }
209
interface Options {
210
  placement: Placement;
211
  modifiers: Array<Partial<Modifier<any, any>>>;
212
  strategy: PositioningStrategy;
213
  onFirstUpdate?: (state: Partial<State>) => void;
214
}
215

216
interface State {
217
  elements: {
218
    reference: Element | VirtualElement;
219
    popper: HTMLElement;
220
    arrow?: HTMLElement;
221
  };
222
  options: Options;
223
  placement: Placement;
224
  strategy: PositioningStrategy;
225
  orderedModifiers: Array<Modifier<any, any>>;
226
  rects: StateRects;
227
  scrollParents: {
228
    reference: Array<Element | Window | VisualViewport>;
229
    popper: Array<Element | Window | VisualViewport>;
230
  };
231
  styles: { [key: string]: Partial<CSSStyleDeclaration> };
232
  attributes: { [key: string]: { [key: string]: string | boolean } };
233
  modifiersData: { [key: string]: any };
234
  reset: boolean;
235
}
236

237
type Placement = 
238
  | 'auto' | 'auto-start' | 'auto-end'
239
  | 'top' | 'top-start' | 'top-end'
240
  | 'bottom' | 'bottom-start' | 'bottom-end'
241
  | 'right' | 'right-start' | 'right-end'
242
  | 'left' | 'left-start' | 'left-end';
243

244
type PositioningStrategy = 'absolute' | 'fixed';
245

246
interface Rect {
247
  width: number;
248
  height: number;
249
  x: number;
250
  y: number;
251
}
252

253
interface Offsets {
254
  x: number;
255
  y: number;
256
}
257

258
type Boundary = Element | Array<Element> | 'clippingParents';
259
type RootBoundary = 'viewport' | 'document';
260
```