1. Docs
  2. Popover

Popover Component

Learn how to implement the Popover component, powered by Flexipop for precise and flexible positioning.

The Popover component in the Flexilla library uses Flexipop, a positioning engine built specifically to handle element placements like popovers, tooltips, and dropdowns.

Installation

To get started, install the @flexilla/popover package, or skip this step if you’ve already installed @flexilla/flexilla.

Structure

Popover Structure

  • popover-trigger: Element that triggers the popover (e.g., on click or hover), with the data-popover-trigger and data-popover-id attributes.
  • popover-content: The content of the popover, with the id attribute.

Example

Initializing the Component

To initialize the component, import Popover and create an instance:
import { Popover } from '@flexilla/popover';

const myPopover = new Popover('#my-popover', { /* options here */ });

Options

The Popover component comes with a range of options to customize its behavior.
type PopoverOptions = {
  defaultState?: "open" | "close", // Set the initial state of the popover.
  preventFromCloseOutside?: boolean, // Prevent closing when clicking outside the popover.
  preventCloseFromInside?: boolean, // Prevent closing when interacting inside the popover.
  placement?: Placement, // Set the popover placement.
  offsetDistance?: number, // Control the offset distance of the popover.
  triggerStrategy?: "click" | "hover", // Determine whether popover opens on click or hover.
  popper?: {
    eventEffect: EventEffect // Customize events on scroll and resize.
  },
  beforeShow?: () => void, // Callback before popover shows.
  beforeHide?: () => void, // Callback before popover hides.
  onShow?: () => void, // Callback after popover shows.
  onHide?: () => void, // Callback after popover hides.
  onToggle?: ({ isHidden }: { isHidden?: boolean }) => void // Callback on toggle.
};
Note: Some options can be passed throught data-* attributes
  • defaultState : data-default-state="Here the state"
  • triggerStrategy : data-trigger-strategy="" Follow this for other too, exept for Callbacks and popper.

Event Effect Options

type EventEffect = {
  disableOnScroll?: boolean, // Disable popover repositioning on scroll.
  disableOnResize?: boolean  // Disable popover repositioning on resize.
};

Example with Options

const myPopover = new Popover('#popover-container', {
  defaultState: 'close',
  preventFromCloseOutside: true,
  placement: 'top',
  offsetDistance: 10,
  triggerStrategy: 'click',
  popper: {
    eventEffect: {
      disableOnScroll: false,
      disableOnResize: false,
    }
  },
  onShow: () => console.log('Popover is shown!'),
  onHide: () => console.log('Popover is hidden!'),
});

Trigger Strategies

The popover can be triggered via click or hover:
  • click: Opens the popover on click.
  • hover: Opens the popover on hover.
<button data-popover-trigger> Click to open </button>
<button data-popover-trigger data-trigger-strategy="hover"> Hover to open </button>

Placement

The popover placement can be customized using the placement option, based on the positions provided by the Flexipop engine.
Available placements:
  • top, top-end,top-start
  • bottom,bottom-end,bottom-start
  • left
  • right
new Popover('.popover', { placement: 'bottom' });

Customizing the Offset

You can control the distance between the popover and the trigger element using offsetDistance:
new Popover('.popover', { offsetDistance: 12 });

Attributes

Attributes options

  • data-placement : define the placement of the popover
  • data-offset-distance : the equivalent of setting offsetDistance in options
  • data-default-state : define a default state of the popover (open|close), the equivalent of options.defaultState, must be (open|close)
  • data-prevent-close-outside : adding this attribute is similar to setting the option preventFromCloseOutside, no value required
  • data-prevent-close-inside : adding this attribute is similar to setting the option preventCloseFromInside, no value required

data-state Attribute

The data-state attribute is used to indicate the state of the popover element:
  • open: Indicates the popover is currently visible.
  • close: Indicates the popover is hidden. You can use this to change the popover Element behavior with CSS (hide, show)
.myPopover{
  display : none;
}
.myPopover[data-state=open]{
  display : block;
}

aria-expanded Attribute

The aria-expanded attribute indicate if the trigger is expanded or not, if expanded true then normal the data-state is open too.
You use it in CSS like to animate the indicator inside the trigger or something else
.myPopover-trigger[aria-expanded=true] .icon-indicator{
  /* style here  */
}

Methods

init(/*options*/)

You can use the Static method if you don’t like to use new Popover(/*options*/) syntax
Popover.init("#myPopover", {/* options */})

Auto Initialization

You can automatically initialize all popovers on the page by calling autoInit():
import { Popover } from '@flexilla/popover';
Popover.autoInit(); // Initializes all popovers with `data-fx-popover`.
The Popover component also exposes methods for programmatic control:

show()

Manually show the popover.
myPopover.show();

hide()

Manually hide the popover.
myPopover.hide();

setShowOptions(/* options */)

Like show() method but here you can set the placement and offsetDistance if needed.
myPopover.setShowOptions({ placement: Placement, offsetDistance: number })