1. Docs
  2. Popover

Popover Component

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

Flexipop
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-target attribute.
  • popover-content: The content of the popover, with the id attribute.

Example 

<button data-popover-trigger data-popover-target="popover-example" class="bg-neutral-800 text-white px-4 py-2 rounded-lg text-sm">
    Show PopOver
</button>
<div data-fx-popover data-popover-content id="popover-example" class="ui-popper invisible opacity-0 fx-open:visible fx-open:opacity-100 w-64 z-20 p-6 bg-zinc-100 dark:bg-zinc-900/50 rounded-md h-48">
    this is content
</div>

Core Styling Requirements

The content element (e.g., the div with id="popover-example") requires specific CSS properties for correct positioning if you are not using the Flexilla UnoCSS preset or the Flexilla Tailwind CSS plugin (which provide a ui-popper utility class).
If you are styling manually, ensure the following CSS is applied to your popover content element: 
.your-popover-content-class { /* Or apply directly to the ID #popover-example */
  position: fixed;
  top: var(--fx-popper-placement-y);
  left: var(--fx-popper-placement-x);
  /* Other styles like width, background, z-index, etc., as needed */
}
Explanation:
  • position: fixed;: This is essential for positioning the element relative to the viewport.
  • top: var(--fx-popper-placement-y);: Flexilla calculates the vertical position and exposes it via this CSS custom property.
  • left: var(--fx-popper-placement-x);: Flexilla calculates the horizontal position and exposes it via this CSS custom property.
If you are using the Flexilla UnoCSS preset or Tailwind plugin, adding the ui-popper class to your content element handles these requirements automatically. For example: <div id="popover-example" class="ui-popper ...other-styles">...</div>

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 through data-* attributes
  • defaultState : data-default-state="Here the state"
  • triggerStrategy : data-trigger-strategy="" Follow this for others too, except 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 indicates if the trigger is expanded. If aria-expanded is true, then typically the data-state will also be open.
You can use it in CSS, for example, to animate an indicator within the trigger. 
.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 })