Package org.patternfly.popper

package org.patternfly.popper
Java wrapper for Popper.js positioning engine used by overlay components.

This package provides a type-safe Java API for Popper.js, the positioning library used by PatternFly components with popups, tooltips, dropdowns, and other floating elements. It handles automatic positioning, collision detection, and dynamic updates.

Key Classes

  • Popper - Main interface for controlling popper instances
  • PopperBuilder - Builder for configuring and creating popper instances
  • Placement - Enum of placement options (top, bottom, left, right, etc.)
  • Modifier - Configuration for Popper.js modifiers
  • TriggerAction - Enum of trigger events (click, hover, focus, etc.)
  • Options - Configuration options for popper behavior
  • State - Current state of the popper including position and styles

Basic Usage

Create a popper to position a floating element relative to a trigger element: 

HTMLElement trigger = button().element();
HTMLElement popup = div().element();

Popper popper = new PopperBuilder("MyComponent", trigger, popup)
    .placement(Placement.bottom)
    .zIndex(1000)
    .registerHandler(Set.of(TriggerAction.click),
        e -> popper.show(() -> console.log("Visible")),
        e -> popper.hide(() -> console.log("Hidden")))
    .build();

Placement Options

Control where the popper appears relative to the trigger element: 

// Automatic placement (Popper chooses the best position)
popper = builder.placement(Placement.auto).build();

// Fixed placement
popper = builder.placement(Placement.top).build();
popper = builder.placement(Placement.bottomStart).build();
popper = builder.placement(Placement.rightEnd).build();

Trigger Actions

Configure how the popper responds to user interactions: 

// Show on hover
builder.registerHandler(Set.of(TriggerAction.mouseenter), show, hide);

// Show on click, hide when clicking outside
builder.registerHandler(Set.of(TriggerAction.click), show, hide);

// Show on focus (for keyboard navigation)
builder.registerHandler(Set.of(TriggerAction.focus), show, hide);

// Stay open even when clicking inside (e.g., for menus)
builder.registerHandler(Set.of(TriggerAction.stayOpen), show, hide);

// Manual control only
builder.registerHandler(Set.of(TriggerAction.manual), show, hide);

Animation and Timing

Configure entrance/exit animations and delays: 

Popper popper = new PopperBuilder(componentName, trigger, popup)
    .animationDuration(300)  // Fade in/out over 300ms
    .entryDelay(500)         // Wait 500ms before showing
    .exitDelay(200)          // Wait 200ms before hiding
    .build();

Modifiers

Customize Popper.js behavior with modifiers: 

// Add offset from trigger element
Modifier offset = new Modifier();
offset.name = "offset";
offset.options = new ModifierOptions();
offset.options.offset = new int[]{0, 8}; // [skidding, distance]

Popper popper = new PopperBuilder(componentName, trigger, popup)
    .addModifier(offset)
    .build();

Controlling Visibility

Programmatically show and hide the popper: 

// Show with callback
popper.show(() -> console.log("Popper is now visible"));

// Hide with callback
popper.hide(() -> console.log("Popper is now hidden"));

// Update position (e.g., after content changes)
popper.update().then(state -> console.log("Updated to: " + state.placement));

// Clean up when done
popper.cleanup();

Lifecycle Management

The PopperBuilder provides lifecycle management options: 

builder
    .removePopperOnTriggerDetach()  // Auto-cleanup when trigger is removed from DOM
    .stayOpen(event -> {             // Custom logic for keeping popper open
        return popup.contains((Node) event.target);
    });
See Also: