- Docs
- 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 thedata-popover-trigger
anddata-popover-id
attributes. -
popover-content
: The content of the popover, with theid
attribute.
Example
this is content
<button data-popover-trigger data-popover-target="popover-example" class="bg-neutral8 text-white px4 py2 rd-lg text-sm">
Show PopOver
</button>
<div data-fx-popover data-popover-content id="popover-example" class="ui-popper invisible op0 fx-open-visible fx-open-op100 w64 z20 p6 bg-zinc1 dark-bg-zinc9/50 rd-md h48">
this is content
</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 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 ofoptions.defaultState
, must be (open|close) -
data-prevent-close-outside
: adding this attribute is similar to setting the optionpreventFromCloseOutside
, no value required -
data-prevent-close-inside
: adding this attribute is similar to setting the optionpreventCloseFromInside
, 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 })