tessl/npm-popperjs--core

Tooltip and popover positioning engine that automatically calculates optimal placement for UI elements with advanced positioning logic and overflow prevention

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Variants and Tree-shaking

Name: tessl/npm-popperjs--core
Author: tessl

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

Capabilities

Full Version (createPopper)

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

/**
 * Full-featured createPopper with all modifiers enabled by default
 * Includes: eventListeners, popperOffsets, computeStyles, applyStyles,
 * offset, flip, preventOverflow, arrow, hide
 */
function createPopper(
  reference: Element | VirtualElement,
  popper: HTMLElement,
  options?: Partial<Options>
): Instance;

Usage Examples:

import { createPopper } from '@popperjs/core';

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

// Bundle size: ~5 kB minzipped

Lite Version (createPopperLite)

Lightweight version with only essential modifiers for basic positioning.

/**
 * Lightweight createPopper with minimal modifiers
 * Includes only: eventListeners, popperOffsets, computeStyles, applyStyles
 * Missing: offset, flip, preventOverflow, arrow, hide
 */
function createPopperLite(
  reference: Element | VirtualElement,
  popper: HTMLElement,
  options?: Partial<Options>
): Instance;

Usage Examples:

import { createPopperLite } from '@popperjs/core';

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

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

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

// Smaller bundle size than full version

Base Version (createPopperBase)

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

/**
 * Base createPopper with no default modifiers
 * Requires all modifiers to be explicitly provided
 */
function createPopperBase(
  reference: Element | VirtualElement,
  popper: HTMLElement,
  options?: Partial<Options>
): Instance;

Usage Examples:

import { 
  createPopperBase,
  popperOffsets,
  computeStyles,
  applyStyles,
  eventListeners
} from '@popperjs/core';

// Must provide all required modifiers
const popper = createPopperBase(button, tooltip, {
  placement: 'top',
  modifiers: [
    eventListeners,
    popperOffsets,
    computeStyles,
    applyStyles,
  ],
});

// Smallest possible bundle - only what you use

popperGenerator Factory

Factory function for creating custom createPopper functions with predefined defaults.

/**
 * Creates a custom createPopper function with predefined modifiers and options
 * @param generatorOptions - Default modifiers and options configuration
 * @returns Custom createPopper function
 */
function popperGenerator(generatorOptions?: PopperGeneratorArgs): typeof createPopper;

interface PopperGeneratorArgs {
  /** Default modifiers to include */
  defaultModifiers?: Array<Modifier<any, any>>;
  /** Default options to apply */
  defaultOptions?: Partial<Options>;
}

Usage Examples:

import { 
  popperGenerator,
  popperOffsets,
  computeStyles,
  applyStyles,
  eventListeners,
  flip,
  preventOverflow
} from '@popperjs/core';

// Create custom build with specific modifiers
const createCustomPopper = popperGenerator({
  defaultModifiers: [
    eventListeners,
    popperOffsets,
    computeStyles,
    applyStyles,
    flip,
    preventOverflow,
  ],
  defaultOptions: {
    placement: 'auto',
    strategy: 'absolute',
  },
});

// Use like standard createPopper
const popper = createCustomPopper(button, tooltip, {
  // placement: 'auto' is default from generator
  modifiers: [
    { name: 'flip', options: { boundary: 'viewport' } },
  ],
});

Tree-shaking Optimization

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

// Individual modifier imports for tree-shaking
import {
  createPopperLite,
  flip,
  preventOverflow,
  offset,
  arrow,
  hide
} from '@popperjs/core';

// Utility function imports
import {
  detectOverflow,
  popperGenerator
} from '@popperjs/core';

Usage Examples:

// Minimal import for basic tooltip
import { createPopperLite } from '@popperjs/core';

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

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

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

// Advanced usage with custom modifiers
import { 
  createPopperBase,
  popperOffsets,
  computeStyles,
  applyStyles,
  eventListeners,
  flip,
  offset,
  detectOverflow
} from '@popperjs/core';

const customModifier = {
  name: 'customFlip',
  enabled: true,
  phase: 'main',
  requires: ['popperOffsets'],
  fn({ state }) {
    const overflow = detectOverflow(state);
    if (overflow.top > 0) {
      state.placement = 'bottom';
    }
  },
};

const advancedPopper = createPopperBase(button, tooltip, {
  modifiers: [
    eventListeners,
    popperOffsets,
    computeStyles,
    applyStyles,
    offset,
    customModifier,
  ],
});

Bundle Size Comparison

Approximate minzipped sizes for different configurations:

// Full version (~5 kB)
import { createPopper } from '@popperjs/core';

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

// Base version with minimal modifiers (~2.5 kB)
import { 
  createPopperBase,
  popperOffsets,
  computeStyles,
  applyStyles
} from '@popperjs/core';

// Custom build with specific features (~3-4 kB)
import { 
  createPopperLite,
  flip,
  preventOverflow,
  offset
} from '@popperjs/core';

Import Patterns

Different ways to import and use Popper variants.

// ESM imports (recommended)
import { createPopper, createPopperLite, createPopperBase } from '@popperjs/core';

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

// UMD (browser globals)
// Available as: Popper.createPopper, Popper.createPopperLite, etc.

Usage Examples:

// ESM with tree-shaking
import { createPopperLite, flip, preventOverflow } from '@popperjs/core';

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

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

// Dynamic imports for code splitting
async function createTooltip() {
  const { createPopperLite, flip } = await import('@popperjs/core');
  return createPopperLite(button, tooltip, {
    modifiers: [flip],
  });
}

Version Selection Guide

Choose the right version based on your requirements:

// Use createPopper (full) when:
// - You need most positioning features
// - Bundle size is not a primary concern
// - You want the "just works" experience

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

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

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

Install with Tessl CLI