0
# Variants and Tree-shaking
1

2
Three different builds for various bundle size requirements and tree-shaking optimization, allowing developers to import only the functionality they need.
3

4
## Capabilities
5

6
### Full Version (createPopper)
7

8
The complete version with all built-in modifiers included by default.
9

10
```javascript { .api }
11
/**
12
 * Full-featured createPopper with all modifiers enabled by default
13
 * Includes: eventListeners, popperOffsets, computeStyles, applyStyles,
14
 * offset, flip, preventOverflow, arrow, hide
15
 */
16
function createPopper(
17
  reference: Element | VirtualElement,
18
  popper: HTMLElement,
19
  options?: Partial<Options>
20
): Instance;
21
```
22

23
**Usage Examples:**
24

25
```javascript
26
import { createPopper } from '@popperjs/core';
27

28
// All modifiers available by default
29
const popper = createPopper(button, tooltip, {
30
  placement: 'top',
31
  // flip, preventOverflow, etc. work automatically
32
});
33

34
// Bundle size: ~5 kB minzipped
35
```
36

37
### Lite Version (createPopperLite)
38

39
Lightweight version with only essential modifiers for basic positioning.
40

41
```javascript { .api }
42
/**
43
 * Lightweight createPopper with minimal modifiers
44
 * Includes only: eventListeners, popperOffsets, computeStyles, applyStyles
45
 * Missing: offset, flip, preventOverflow, arrow, hide
46
 */
47
function createPopperLite(
48
  reference: Element | VirtualElement,
49
  popper: HTMLElement,
50
  options?: Partial<Options>
51
): Instance;
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
import { createPopperLite } from '@popperjs/core';
58

59
// Basic positioning only
60
const popper = createPopperLite(button, tooltip, {
61
  placement: 'bottom',
62
});
63

64
// Add specific modifiers as needed
65
import { createPopperLite, preventOverflow, flip } from '@popperjs/core';
66

67
const popper = createPopperLite(button, tooltip, {
68
  placement: 'top',
69
  modifiers: [preventOverflow, flip],
70
});
71

72
// Smaller bundle size than full version
73
```
74

75
### Base Version (createPopperBase)
76

77
Minimal version with no default modifiers - all functionality must be explicitly imported.
78

79
```javascript { .api }
80
/**
81
 * Base createPopper with no default modifiers
82
 * Requires all modifiers to be explicitly provided
83
 */
84
function createPopperBase(
85
  reference: Element | VirtualElement,
86
  popper: HTMLElement,
87
  options?: Partial<Options>
88
): Instance;
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
import { 
95
  createPopperBase,
96
  popperOffsets,
97
  computeStyles,
98
  applyStyles,
99
  eventListeners
100
} from '@popperjs/core';
101

102
// Must provide all required modifiers
103
const popper = createPopperBase(button, tooltip, {
104
  placement: 'top',
105
  modifiers: [
106
    eventListeners,
107
    popperOffsets,
108
    computeStyles,
109
    applyStyles,
110
  ],
111
});
112

113
// Smallest possible bundle - only what you use
114
```
115

116
### popperGenerator Factory
117

118
Factory function for creating custom createPopper functions with predefined defaults.
119

120
```javascript { .api }
121
/**
122
 * Creates a custom createPopper function with predefined modifiers and options
123
 * @param generatorOptions - Default modifiers and options configuration
124
 * @returns Custom createPopper function
125
 */
126
function popperGenerator(generatorOptions?: PopperGeneratorArgs): typeof createPopper;
127

128
interface PopperGeneratorArgs {
129
  /** Default modifiers to include */
130
  defaultModifiers?: Array<Modifier<any, any>>;
131
  /** Default options to apply */
132
  defaultOptions?: Partial<Options>;
133
}
134
```
135

136
**Usage Examples:**
137

138
```javascript
139
import { 
140
  popperGenerator,
141
  popperOffsets,
142
  computeStyles,
143
  applyStyles,
144
  eventListeners,
145
  flip,
146
  preventOverflow
147
} from '@popperjs/core';
148

149
// Create custom build with specific modifiers
150
const createCustomPopper = popperGenerator({
151
  defaultModifiers: [
152
    eventListeners,
153
    popperOffsets,
154
    computeStyles,
155
    applyStyles,
156
    flip,
157
    preventOverflow,
158
  ],
159
  defaultOptions: {
160
    placement: 'auto',
161
    strategy: 'absolute',
162
  },
163
});
164

165
// Use like standard createPopper
166
const popper = createCustomPopper(button, tooltip, {
167
  // placement: 'auto' is default from generator
168
  modifiers: [
169
    { name: 'flip', options: { boundary: 'viewport' } },
170
  ],
171
});
172
```
173

174
### Tree-shaking Optimization
175

176
Import only the modifiers and utilities you need for optimal bundle size.
177

178
```javascript { .api }
179
// Individual modifier imports for tree-shaking
180
import {
181
  createPopperLite,
182
  flip,
183
  preventOverflow,
184
  offset,
185
  arrow,
186
  hide
187
} from '@popperjs/core';
188

189
// Utility function imports
190
import {
191
  detectOverflow,
192
  popperGenerator
193
} from '@popperjs/core';
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
// Minimal import for basic tooltip
200
import { createPopperLite } from '@popperjs/core';
201

202
const basicPopper = createPopperLite(button, tooltip, {
203
  placement: 'top',
204
});
205

206
// Progressive enhancement - add features as needed
207
import { createPopperLite, flip, preventOverflow } from '@popperjs/core';
208

209
const enhancedPopper = createPopperLite(button, tooltip, {
210
  placement: 'top',
211
  modifiers: [flip, preventOverflow],
212
});
213

214
// Advanced usage with custom modifiers
215
import { 
216
  createPopperBase,
217
  popperOffsets,
218
  computeStyles,
219
  applyStyles,
220
  eventListeners,
221
  flip,
222
  offset,
223
  detectOverflow
224
} from '@popperjs/core';
225

226
const customModifier = {
227
  name: 'customFlip',
228
  enabled: true,
229
  phase: 'main',
230
  requires: ['popperOffsets'],
231
  fn({ state }) {
232
    const overflow = detectOverflow(state);
233
    if (overflow.top > 0) {
234
      state.placement = 'bottom';
235
    }
236
  },
237
};
238

239
const advancedPopper = createPopperBase(button, tooltip, {
240
  modifiers: [
241
    eventListeners,
242
    popperOffsets,
243
    computeStyles,
244
    applyStyles,
245
    offset,
246
    customModifier,
247
  ],
248
});
249
```
250

251
### Bundle Size Comparison
252

253
Approximate minzipped sizes for different configurations:
254

255
```javascript
256
// Full version (~5 kB)
257
import { createPopper } from '@popperjs/core';
258

259
// Lite version (~3.5 kB) 
260
import { createPopperLite } from '@popperjs/core';
261

262
// Base version with minimal modifiers (~2.5 kB)
263
import { 
264
  createPopperBase,
265
  popperOffsets,
266
  computeStyles,
267
  applyStyles
268
} from '@popperjs/core';
269

270
// Custom build with specific features (~3-4 kB)
271
import { 
272
  createPopperLite,
273
  flip,
274
  preventOverflow,
275
  offset
276
} from '@popperjs/core';
277
```
278

279
### Import Patterns
280

281
Different ways to import and use Popper variants.
282

283
```javascript { .api }
284
// ESM imports (recommended)
285
import { createPopper, createPopperLite, createPopperBase } from '@popperjs/core';
286

287
// CommonJS
288
const { createPopper, createPopperLite, createPopperBase } = require('@popperjs/core');
289

290
// UMD (browser globals)
291
// Available as: Popper.createPopper, Popper.createPopperLite, etc.
292
```
293

294
**Usage Examples:**
295

296
```javascript
297
// ESM with tree-shaking
298
import { createPopperLite, flip, preventOverflow } from '@popperjs/core';
299

300
// CommonJS fallback
301
const Popper = require('@popperjs/core');
302
const { createPopperLite, flip, preventOverflow } = Popper;
303

304
// Browser with CDN
305
// <script src="https://unpkg.com/@popperjs/core@2"></script>
306
const popper = Popper.createPopper(button, tooltip);
307

308
// Dynamic imports for code splitting
309
async function createTooltip() {
310
  const { createPopperLite, flip } = await import('@popperjs/core');
311
  return createPopperLite(button, tooltip, {
312
    modifiers: [flip],
313
  });
314
}
315
```
316

317
### Version Selection Guide
318

319
Choose the right version based on your requirements:
320

321
```javascript
322
// Use createPopper (full) when:
323
// - You need most positioning features
324
// - Bundle size is not a primary concern
325
// - You want the "just works" experience
326

327
// Use createPopperLite when:
328
// - You need basic positioning with some advanced features
329
// - Bundle size matters but you still want tree-shaking
330
// - You'll add specific modifiers as needed
331

332
// Use createPopperBase when:
333
// - Bundle size is critical
334
// - You need only specific functionality
335
// - You're building a custom solution
336
// - You want maximum control over included features
337

338
// Use popperGenerator when:
339
// - You're building a library or framework
340
// - You need consistent defaults across multiple poppers
341
// - You want to encapsulate configuration
342
```