Espalier components → Popover

import "@taprootio/espalier/popover";

<esp-popover>

Display a contextual UI overlay that appears when a user interacts with an element, providing a temporary space for additional information, options, or actions without blocking the underlying content. Uses the native Popover API to render in the browser's top layer, escaping all ancestor overflow and z-index contexts.

Slots

<esp-popover> has the following slots:

target

The target listens for events to show the popover.

The content to be shown in a popover.

Attributes

<esp-popover> has the following attributes:

attach

attach has a default value of "below".

Attach determines which side of the target the popover will appear on. With the default collision="flip", the popover tries the specified side first but may use the opposite side when it has more room. Use collision="shift" to preserve this requested side while shifting the panel into the viewport, or collision="none" to disable adjustment. It can be one of the following:

Place above

Place below (default)

Place to left

Place to right

collision

collision has a default value of "flip".

Determines how the popover responds when its natural placement would leave the viewport:

"flip" moves the popover to the opposite side when that side has more room, then constrains it horizontally. This is the default and preserves the existing behavior.
"shift" keeps the requested attach side and shifts the popover within the viewport. Oversized panels are pinned to the viewport's top or left edge and may overlap content beyond the trigger.
"none" keeps the requested side without viewport adjustment.

Use shift when the attachment side conveys meaning and a partial overlap is preferable to flipping the panel:

align

align has a default value of "start".

Align determines how the popover is aligned relative to the target. For example, if attach is "below" and align is "start", the popover will appear below the target, aligned to the left edge of the target.

Place below, align start

Place below, align center

Place below, align end

Place right, align start

Place right, align center

Place right, align end

offset

offset has a default value of "".

The offset value determines the distance between the popover and the target when the popover is shown.

offset-x

offset-x has a default value of 0.

Additional horizontal pixel offset applied after the popover is positioned. Positive moves right, negative left. Useful for anchoring a popover to a dynamic point within a large target element.

offset-y

offset-y has a default value of 0.

Additional vertical pixel offset applied after the popover is positioned. Positive moves down, negative up. Useful for anchoring a popover to a dynamic point within a large target element.

trigger

trigger has a default value of "click".

The event to listen for on the target to open the popover.

"click" — toggle on click (default).
"hover" — open on mouseenter, close on mouseleave.
"focus" — open on focusin, close on focusout.
"focus-hover" — open on hover or focus; close only when both hover and focus are lost. Ideal for tooltips.
"none" — no automatic trigger; open/close programmatically.

show-delay

show-delay has a default value of 0.

Delay in milliseconds before showing the popover after the trigger event fires. Useful for tooltips so they don't flash on quick mouse-overs.

hide-delay

hide-delay has a default value of 0.

Delay in milliseconds before hiding the popover after the trigger condition is lost. Gives the user time to move the cursor from the trigger into the popover content.

Events

<esp-popover> emits the following events:

esp-popover-opened is of type CustomEvent.

Emitted when the popover is opened.

esp-popover-closed is of type CustomEvent.

Emitted when the popover is closed.

Popover