Introduction

The Popover component is an interactive overlay element that displays additional details, actions, or contextual forms in a floating card positioned relative to an anchor trigger element.

Built specifically with our Zero-JS static rendering architecture and conditional hydration model in mind, the Popover uses efficient page builder-friendly bindings. It remains completely static in the HTML layout until hydrated as an interactive Preact island to handle toggle and escape triggers smoothly.

Usage

These examples illustrate how content authors configure and bind popover blocks.

1. Basic Informational Popover

A clean, text-only popover, ideal for explaining terms, offering definitions, or showing light helper messages without cluttering the main page layout.

{
  "type": "popover",
  "triggerText": "Learn More",
  "title": "Data Residency",
  "description": "Your profile data is stored securely in compliant Frankfurt (EU) server nodes."
}

2. Advanced Popover with Body Content and Footer Actions

An onboarding popover containing distinct sections: an informative header, body text, and custom action buttons nested in the footer slot.

{
  "type": "popover",
  "triggerText": "Setup Account",
  "title": "Configure API Integrations",
  "description": "Connect with external tools seamlessly.",
  "body": "Your subscription allows up to 5 concurrent server channels. Ensure your client secret credentials are copied before proceeding.",
  "footer": "Connect Keys",
  "showArrow": true
}

3. Popover with Custom SVG Trigger and Nested Child Blocks

For more complex dashboard panels, popovers can embed custom SVG triggers (using raw markup inside triggerIcon) and render lists of child components (like nested Badges, Text, or additional Action Buttons) inside their floating card.

{
  "type": "popover",
  "triggerText": "System Status",
  "triggerIcon": "<circle cx=\"12\" cy=\"12\" r=\"10\" /><line x1=\"12\" y1=\"16\" x2=\"12\" y2=\"12\" /><line x1=\"12\" y1=\"8\" x2=\"12.01\" y2=\"8\" />",
  "triggerAriaLabel": "System Operations Status Info",
  "title": "System Heartbeat",
  "description": "Operational health checks",
  "showArrow": true,
  "closable": true,
  "children": [
    {
      "blockType": "badge",
      "text": "API: OK",
      "colorPalette": "green"
    },
    {
      "blockType": "badge",
      "text": "DB: OK",
      "colorPalette": "green"
    }
  ]
}

Props

Architecture Notes

• Smart Viewport Boundary Alignments: The interactive Preact island dynamically tracks screen space. If the popover opens near viewport edges, it flips directions automatically (e.g. from bottom to top alignment) and shifts along its axis to prevent content clipping.
• Unified Event Delegation: Opening and closing interactions, along with close-on-click-outside and escape-key handling, are delegated cleanly from a central listener on the popover's root element. This minimizes client-side event binding.
• Semantic Overlays: Popovers compile into native, accessible layouts incorporating semantic attributes like role="dialog", aria-haspopup="dialog", and aria-expanded="true|false" out-of-the-box, ensuring full screen-reader compliance.