Popper

Add Smart Positioning to every Popper component on the page. Each Popper is expected to be wrapped in a parent element with the class popper, and includes a popper-navigation element (the positioning container) and a popper-content element (the content that must remain inside the viewport).

‍

Preferred Position (Reset Behavior)

The script treats the initial positioning state as the Popper’s “preferred” placement:

• If popper-navigation has no positioning addon class, the default placement is treated as bottom-center (no class required).
• If a positioning addon class exists (any class starting with is-float-, is-overlay-, or is-overlay), that class is stored as the preferred placement.

On every recalculation (open, scroll, resize, or content size change), the script first restores the Popper to its preferred placement. If the Popper fits inside the viewport, no further changes are made. This ensures the Popper always returns to its intended default position whenever possible.

‍

Viewport Overflow Detection

The script measures the popper-content element using getBoundingClientRect() and checks whether it overflows the viewport, with a small padding buffer to prevent edge-touching. Overflow can be detected on any side (top, right, bottom, left).

‍

Center Alignment Adjustment

If the Popper is using a centered placement:

• bottom (including the default/no-addon state)
• top

…and the content overflows horizontally, the script shifts alignment before flipping the Popper:

• Overflowing the left side switches to left aligned
• Overflowing the right side switches to right aligned

This keeps the Popper on the same vertical side (above or below) while correcting horizontal clipping.

‍

Auto Flip (Opposite Side)

If the Popper still overflows after the center alignment adjustment, the script automatically flips the Popper to the opposite side by replacing the current is-float-* or is-overlay-* addon with its matching opposite:

• bottom-* flips to top-*
• top-* flips to bottom-*
• start-* flips to end-*
• end-* flips to start-*

This flip check can run up to two times to ensure the Popper resolves fully into a visible position.

Flip behavior adapts based on placement type:

• Top / Bottom placements flip vertically (top ↔ bottom)
• Left / Right placements flip horizontally (left ↔ right)
• Start / End alignment may switch to prevent vertical overflow
• Diagonal placements switch both side and alignment as needed

‍

Arrow / Bridge Sync

The script automatically keeps the Popper arrow system visually aligned with the final resolved placement.

• popper-bridge controls direction (top / left / right)
• popper-arrow controls side alignment for left/right placements

This syncing is applied only for standard float poppers.

Rules:

• Sync is applied only when using is-float-* placements
• Sync is not applied for:
  • is-overlay-*
  • is-overlay
  • is-diagonal

Behavior:

• Side placements apply is-left / is-right to both popper-bridge and popper-arrow
• Top placements apply is-top to popper-bridge
• Bottom placements remain default (no addon classes)
• All bridge and arrow classes are automatically reset and reapplied on each update

This ensures arrow elements always reflect the final resolved position without requiring manual setup.

‍

When It Recalculates

The Popper recalculates automatically when:

• A popper-toggle is clicked (open interaction)
• popper-navigation changes class/style (through interactions)
• popper-content resizes (dynamic content, CMS, responsive type)
• The viewport resizes or the page scrolls

This keeps Popper positioning consistent across breakpoints, scroll positions, and changing content.