@papit/popover

a positioned overlay built on the native Popover API and CSS Anchor Positioning

installation

npm install @papit/popover

to use in html

<script type="module" defer>
  import "@papit/popover";
</script>

<button popovertarget="my-pop">Open</button>
<pap-popover id="my-pop"> content goes here </pap-popover>

usage

Connect any trigger element using the standard popovertarget attribute. The popover anchors itself automatically — no coordinate math needed.

trigger actions

Control behaviour via popovertargetaction on the trigger:

| Value | Behaviour | | --------- | ------------------------------------------------------------------------- | | (none) | Toggle open/closed on click | | "show" | Open only | | "hide" | Close only | | "hover" | Open on mouse enter, close on leave (with safe hover zone across the gap) |

<!-- hover trigger -->
<button popovertarget="tip" popovertargetaction="hover">Hover me</button>
<pap-popover id="tip" placement="top">tooltip text</pap-popover>

placement

The placement attribute controls where the popover appears relative to its trigger. Single-axis values (top, bottom, left, right) resolve to their centered variant.

top-left     top / top-center     top-right

left-top                            right-top
left / left-center              right / right-center
left-bottom                         right-bottom

bottom-left  bottom / bottom-center  bottom-right

multiple triggers

Any number of triggers can target the same popover. Each activation re-anchors it to the triggering element.

<button popovertarget="ctx">Item A</button>
<button popovertarget="ctx">Item B</button>
<pap-popover id="ctx" placement="bottom-left">context menu</pap-popover>

programmatic control

const popover = document.querySelector("pap-popover");

popover.show(triggerElement); // show, anchored to element
popover.hide(); // hide
popover.toggle(triggerElement); // toggle, anchored to element

properties

| Property | Type | Default | Description | | ----------- | --------- | ---------- | -------------------------------------------------- | | open | boolean | false | Whether the popover is visible | | placement | string | "bottom" | Preferred placement relative to the trigger anchor |

keyboard

| Key | Behaviour | | ----- | ------------- | | Esc | Close popover |

Contributing

Contributions are welcome! Please follow the development guidelines above and ensure all tests pass before submitting a pull request.

License

Licensed under the @Papit License 1.0 - Copyright (c) 2024 Henry Pap (@onkelhoy)

Key points:

• ✅ Free to use in commercial projects
• ✅ Free to modify and distribute
• ✅ Attribution required
• ❌ Cannot resell the component itself as a standalone product

See the LICENSE file for full details.

Related Components

• @papit/web-component: Core utilities, decorators, and base component class

Support

For issues, questions, or contributions, please visit the GitHub repository.