Popover

Popover renders a floating content panel near a target element. It is designed for richer contextual UI than a tooltip, such as short descriptions, small action areas, helper content, or compact interactive blocks.

Popover opens on click by default and can also be controlled manually through the JavaScript API. In React, Popover is initialized through the usePopover hook without adding popover attributes to the element. In vanilla usage, FrontAlign can observe popover components automatically through the component engine.

Getting Started

Use the React hook for framework usage, or create an instance manually when working with plain JavaScript.

import { Popover } from 'frontalign';

const popover = new Popover('#info-btn', {
  title: 'Popover title',
  content: 'Popover content',
  placement: 'bottom'
});

Automatic Initialization

Elements marked with the fa-component="popover" attribute are picked up automatically by FrontAlign's component engine — no manual new Popover(...) call is required.

All data-* attributes on the element (see Data Attributes below) are read as configuration when the instance is created.

<button
  fa-component="popover"
  data-title="Account status"
  data-content="Your account is active."
  data-placement="bottom"
>
  Open
</button>

Placement

Popover supports five placement values. The default auto mode measures available viewport space around the target and picks the best fit.

new Popover('#btn', { placement: 'auto'   }); // smart placement
new Popover('#btn', { placement: 'top'    });
new Popover('#btn', { placement: 'bottom' });
new Popover('#btn', { placement: 'left'   });
new Popover('#btn', { placement: 'right'  });

Content

Popover can render a title, content, or both. Use target when you want to clone content from an existing element or template.

new Popover('#info-btn', {
  title: 'Account status',
  content: 'Your account is active.',
  placement: 'bottom'
});

new Popover('#template-btn', {
  target: '#account-popover-template',
  placement: 'bottom'
});

Trigger Modes

The default trigger is click. Use manual when the instance should only be opened or closed through JavaScript methods.

// Click toggle, default behavior
new Popover('#click-btn', {
  title: 'Click popover',
  content: 'I toggle on click.',
  trigger: 'click'
});

// Manual control
const popover = new Popover('#manual-btn', {
  title: 'Manual popover',
  content: 'Controlled from JavaScript.',
  trigger: 'manual'
});

popover.show();
popover.hide();
popover.toggle();

Arrow

Set hasArrow: true to render a directional arrow pointing toward the target. Enabled by default.

new Popover('#btn', { title: 'With arrow',    hasArrow: true  });
new Popover('#btn', { title: 'Without arrow', hasArrow: false });

Auto Clean

Set autoClean: true to have the instance call .dispose() automatically after the popover is hidden. Useful for dynamic lists where manual cleanup is impractical.

new Popover('#btn', {
  title: 'Auto clean',
  content: 'This popover disposes after it is hidden.',
  placement: 'bottom',
  autoClean: true
});

Configuration Reference

Data Attributes

Every option except autoClean can also be set declaratively on the trigger element. Data attributes are only read once, at instantiation — see Automatic Initialization.

Options passed to the constructor always take priority over data-* attributes, which in turn take priority over the built-in defaults.

Class Reference

Events

Popover dispatches lifecycle events on the trigger element. fa.popover.show and fa.popover.hide are cancelable — calling preventDefault() on them stops the corresponding action before anything changes. Every event's detail carries { instance, trigger, popover }, where popover is the generated .popover element (null while it doesn't exist yet).

const trigger = document.querySelector('#info-btn');

trigger.addEventListener('fa.popover.shown', (event) => {
  console.log('opened', event.detail.popover);
});

trigger.addEventListener('fa.popover.hidden', (event) => {
  console.log('closed');
});