1. Docs
  2. Popper

Flexipop - Positioning Engine for Flexilla

Flexipop is a lightweight and efficient positioning engine tailored for Flexilla, offering seamless popper-like functionality with minimal overhead.

Installation

Install Flexipop via npm: 
npm i flexipop

Basic Usage

To use Flexipop, you simply need to create an instance of CreatePopper, passing the reference element and the popper element along with any custom options you may require: 
import { CreatePopper } from 'flexipop';

new CreatePopper(
  referenceElement,  // The element relative to which the popper will be positioned (HTMLElement)
  popperElement,     // The popper element to be positioned (HTMLElement)
  {
    // options here
  }
);

Example HTML Markup 

<div data-reference-el></div>
<div data-popper-el>Left-start</div>
Note: The popperElement should have its position set to fixed.
Bottom

Required Styles for the popperElement 

.myPopper{
  position: fixed;
  top: var(--fx-popper-placement-y);
  left: var(--fx-popper-placement-x);
}

Usage with position: absolute

Flexipop also supports poppers with position: absolute. This is useful when the reference and popper elements are within the same container, and you need the popper to behave according to the flow of the containing element.

Setup for Absolute Positioning

Use the same CreatePopper constructor — simply set position: absolute on the popper element and position: relative on the parent container. 
import { CreatePopper } from 'flexipop';

new CreatePopper(
  referenceElement,  // The reference element (HTMLElement)
  popperElement,     // The popper element (HTMLElement)
  {
    // options here
  }
);

Requirements

  • The popperElement must have its position set to absolute.
  • Both the referenceElement and popperElement should be in the same parent container.
  • The parent container must have its position set to relative.

Example HTML Markup for Absolute Positioning 

<div class="relative-container" style="position: relative;">
  <div data-reference-el></div>
  <div data-popper-el>Absolute popper</div>
</div>
  • CSS 
.myPopper{
  position: absolute;
  top: var(--fx-popper-placement-y);
  left: var(--fx-popper-placement-x);
}
Important: Ensure that the parent container has position: relative, and the popperElement has position: absolute.

Options

The options provided to Flexipop help control how your popper is positioned. You can set placement, offsets, and more to adjust its behavior.

Available Options

  • placement: Defines the position of the popper relative to the reference element (top, bottom, left, right, with alignment options like -start, -end, -middle).
    Example: 
    new CreatePopper(referenceElement, popperElement, { placement: 'bottom-end' });
  • offsetDistance: Adds a specific distance (in pixels) between the reference and popper elements. 
    new CreatePopper(referenceElement, popperElement, { offsetDistance: 16 });
    Default: 10
  • eventEffect: Controls whether the popper repositions on scroll and/or resize. 
    type EventEffect = {
  disableOnScroll?: boolean, // Disable repositioning on scroll
  disableOnResize?: boolean  // Disable repositioning on resize
}
    new CreatePopper(referenceElement, popperElement, {
  eventEffect: {
    disableOnScroll: false,
    disableOnResize: true,
  }
});
  • onUpdate: A callback invoked every time the popper position is recalculated. Receives { x, y, placement }. 
    new CreatePopper(referenceElement, popperElement, {
  onUpdate: ({ x, y, placement }) => {
    console.log(`Popper at ${x}, ${y} (${placement})`);
  }
});
  • readjustHeight: When true, the popper’s maxHeight and overflowY are adjusted so the popper fits within the viewport. Useful for dropdowns and select menus with long item lists. 
    new CreatePopper(referenceElement, popperElement, { readjustHeight: true });
    Default: false
  • minHeight: Minimum height (in pixels) enforced when readjustHeight is active. If the available viewport space is less than minHeight, the popper flips instead of shrinking further.
    Default: 140

Full Options Type 

type PopperOptions = {
  placement?: Placement,
  offsetDistance?: number,
  eventEffect?: {
    disableOnScroll?: boolean,
    disableOnResize?: boolean
  },
  onUpdate?: ({ x, y, placement }: { x: number, y: number, placement?: Placement }) => void,
  readjustHeight?: boolean,
  minHeight?: number
}

Placement

The placement option defines where the popper appears relative to the reference element. Each direction supports alignment suffixes:
Direction Alignments
top top-start, top-middle, top-end
bottom bottom-start, bottom-middle, bottom-end
left left-start, left-middle, left-end
right right-start, right-middle, right-end
When there isn’t enough space in the requested direction, Flexipop automatically flips to the opposite side. 
new CreatePopper(referenceElement, popperElement, { placement: 'bottom-middle' });
If the popper doesn’t fit on the flipped side either, Flexipop will align it to keep as much of it visible as possible within the viewport.

CSS Custom Properties

During positioning, Flexipop sets the following CSS custom properties on the popper element:
Property Description
--fx-popper-placement-x The computed left position in pixels
--fx-popper-placement-y The computed top position in pixels
--trigger-width The reference element’s width in pixels
The popper also receives a data-show-placement attribute reflecting the resolved placement (which may differ from the requested one if a flip occurred). 
.myPopper {
  position: fixed;
  top: var(--fx-popper-placement-y);
  left: var(--fx-popper-placement-x);
}

Methods

updatePosition()

Recalculates and applies the popper position. Call this when the reference element moves (e.g., after layout changes) or after the popper content changes size. 
const popper = new CreatePopper(referenceElement, popperElement);
popper.updatePosition();

setOptions({ placement, offsetDistance })

Updates the placement and/or offset distance, then immediately recalculates the position. 
popper.setOptions({ placement: 'right', offsetDistance: 20 });

resetPosition()

Clears all positioning styles (the CSS custom properties) and resets maxHeight/overflowY. Useful when hiding the popper. 
popper.resetPosition();

cleanupEvents()

Removes all window event listeners (resize/scroll) and clears positioning styles. Call this when the popper is no longer needed. 
popper.cleanupEvents();