Popover

A floating panel anchored to a trigger element. Supports static HTML content or remote AJAX content, hover (default) or click triggers, and smart viewport-aware placement. The popover is rendered to <body> and uses position: absolute so it scrolls naturally with the document — no JavaScript scroll tracking needed. When the popover is clamped near a viewport edge the arrow always adjusts to keep pointing at the trigger element. Popovers are ideal for contextual info cards, user profile previews, and rich tooltips.

Basic Hover Popover

Default behaviour: shows on hover with a short delay, hides when the mouse leaves the trigger or the popover itself. Placement defaults to auto (prefers bottom).

Click Trigger

Use ->triggerOn('click') for click-to-toggle behaviour. Clicking outside the popover or pressing Escape dismisses it.

Placement

Explicit top, bottom, left, and right placements, plus auto (default — flips to top when near the bottom edge).

Remote Content (AJAX)

Use ->remote(url) to load the popover body from an endpoint on first show. Responses are cached per URL by default — set ->cache(false) to always re-fetch. A spinner is shown while loading.

Shared Popover — User Profile Cards

A single popover instance can serve many triggers via ->triggerSelector(). Each trigger passes per-trigger overrides using data-popover-title and data-popover-content (or data-popover-url for AJAX overrides). This is the recommended pattern for user profile cards on a username list.

Mentioned by: @alice, @bob, @carmen

Interact with the examples above to see events here…

// Static content, single trigger (hover by default)
<?= $m->popover('info-pop')
      ->trigger('info-btn')
      ->title('Quick Info')
      ->content('<p>Details here.</p>')
      ->placement('bottom') ?>

// Click trigger
<?= $m->popover('click-pop')
      ->trigger('click-btn')
      ->title('Click Popover')
      ->triggerOn('click')
      ->content('<p>Click outside to close.</p>') ?>

// Remote / AJAX content
<?= $m->popover('remote-pop')
      ->trigger('remote-btn')
      ->title('User Profile')
      ->remote('/api/user/card?id=42')
      ->width('280px') ?>

// Shared popover for multiple triggers (user profile cards)
<?= $m->popover('profile-pop')
      ->triggerSelector('.username-link')
      ->placement('bottom')
      ->delay(150, 300)
      ->width('260px') ?>

// Each trigger carries per-trigger overrides:
<a class="username-link"
   data-popover-title="Jane Smith"
   data-popover-url="/profile/card?id=5">@jane</a>

// Or inline content override:
<a class="username-link"
   data-popover-title="Jane Smith"
   data-popover-content="<p>Inline content</p>">@jane</a>

// Programmatic binding for dynamically added triggers:
document.querySelectorAll('.new-link').forEach(function(el) {
    m.popover('profile-pop').bindTrigger(el);
});

// Get the popover API
var pop = m.popover('my-pop');

// Show anchored to any element
pop.show(document.getElementById('my-btn'));

// Hide
pop.hide();

// Toggle for a trigger element
pop.toggle(document.getElementById('my-btn'));

// Update content on demand
pop.setContent('<p>New content</p>');
pop.setTitle('New title');

// Load content from a URL
pop.loadContent('/api/details');

// Manually bind a new trigger (after dynamic DOM insertion)
pop.bindTrigger(someNewElement);

// Re-scan DOM for triggers added after init
pop.refresh();

// Listen for events
document.getElementById('my-pop').addEventListener('m:popover:show', function(e) {
    console.log('shown for trigger', e.detail.trigger);
});

document.getElementById('my-pop').addEventListener('m:popover:content-loaded', function(e) {
    console.log('loaded from', e.detail.url);
});

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->popover($id)`	`Popover`	Create a new popover component.
`->title($text)`	`self`	Set the header title text.
`->content($html)`	`self`	Set static HTML for the popover body.
`->trigger($elementId)`	`self`	Bind to a single DOM element by ID.
`->triggerSelector($css)`	`self`	Bind to all elements matching a CSS selector.
`->placement($p)`	`self`	Placement: `auto` (default), `top`, `bottom`, `left`, `right`.
`->align($a)`	`self`	Horizontal alignment for top/bottom placements: `center` (default), `start` (left-edge), `end` (right-edge). No effect on left/right placements.
`->triggerOn($event)`	`self`	Trigger event: `hover` (default) or `click`.
`->delay($show, $hide)`	`self`	Show/hide delays in ms. Default: 200 / 300.
`->remote($url)`	`self`	Load body content from a URL via AJAX.
`->cache($bool)`	`self`	Cache remote responses per URL. Default: `true`.
`->width($css)`	`self`	Force a specific CSS width, e.g. `'300px'`.
`->offset($px)`	`self`	Gap between trigger and popover in pixels. Default: `8`.

JS JS Methods

Method / Property	Parameters	Description
`m.popover(id)`	`object\|null`	Get a popover instance by ID (auto-inits on DOMContentLoaded).
`pop.show(triggerEl)`		Show the popover anchored to an element.
`pop.hide()`		Hide the popover.
`pop.toggle(triggerEl)`		Toggle visibility for a trigger element.
`pop.setContent(html)`		Replace the body with arbitrary HTML.
`pop.setTitle(text)`		Update the header title text.
`pop.loadContent(url, force)`		Fetch content from a URL. Pass `true` to bypass cache.
`pop.bindTrigger(el)`		Bind a DOM element as a trigger (safe to call multiple times).
`pop.refresh()`		Re-scan the DOM for new trigger elements matching the configured selector.
`pop.element`	`HTMLElement`	The underlying popover DOM element.

EVENT Events

Event Name	Detail	Description
`m:popover:show`	`{ id, trigger }`	Fired on the popover element when it becomes visible.
`m:popover:hide`	`{ id }`	Fired when the popover is hidden.
`m:popover:content-loaded`	`{ id, url }`	Fired after remote content is successfully loaded and injected.