Popover

Introduction

Popovers are overlays that display a .popover-header title, a .popover-body body, and a directional arrow. The Popover plugin extends Tooltip — it shares the same Floating UI positioning engine, placement logic, and lifecycle events, and adds a content slot and a default trigger of click instead of hover focus.

Key behaviors:

• Elements with data-cx-toggle="popover" initialize automatically on first click, focus, or hover — no JavaScript is required for the data API.
• A popover with both title and content empty is never shown.
• The default placement is right; the default trigger is click.
• Calling show on a hidden element (inline style.display: none) throws an error.
• Popovers on disabled elements must be attached to a wrapper element.
• Hide a popover before removing its trigger element from the DOM.
• Trigger elements inside a shadow DOM are supported.

Basic structure

Add data-cx-toggle="popover" to a button or link, set data-cx-title for the header, data-cx-content for the body, or both. At least one must be non-empty for the popover to appear.

<button type="button" class="button primary"
  data-cx-toggle="popover"
  data-cx-title="Popover title"
  data-cx-content="Body content goes here.">
Toggle popover
</button>

The plugin generates the following markup and appends it to document.body (or the configured container):

<div class="popover cx-popover-auto" role="tooltip">
  <div class="popover-arrow"></div>
  <h3 class="popover-header">Popover title</h3>
  <div class="popover-body">Body content goes here.</div>
</div>

The cx-popover-auto class reads the data-cx-placement attribute written by Floating UI after each position computation and applies the styles of the matching directional class (cx-popover-top, cx-popover-end, cx-popover-bottom, or cx-popover-start) to position the arrow. The trigger element receives aria-describedby pointing at the generated element's id while the popover is visible; the attribute is removed on hide.

Placement

Set data-cx-placement on the trigger to control which side the popover appears on. The logical values start and end resolve to the inline-start and inline-end sides and adapt to the document's text direction. The physical values left, right, top, and bottom always place the popover on that side regardless of direction. The default is right.

<button type="button" class="button secondary"
  data-cx-toggle="popover"
  data-cx-content="Top"
  data-cx-placement="top">
top
</button>
<button type="button" class="button secondary"
  data-cx-toggle="popover"
  data-cx-content="Bottom"
  data-cx-placement="bottom">
bottom
</button>
<button type="button" class="button secondary"
  data-cx-toggle="popover"
  data-cx-content="Start"
  data-cx-placement="start">
start
</button>
<button type="button" class="button secondary"
  data-cx-toggle="popover"
  data-cx-content="End"
  data-cx-placement="end">
end
</button>
<button type="button" class="button secondary"
  data-cx-toggle="popover"
  data-cx-content="Left"
  data-cx-placement="left">
left
</button>
<button type="button" class="button secondary"
  data-cx-toggle="popover"
  data-cx-content="Right"
  data-cx-placement="right">
right
</button>

When the preferred placement would cause the popover to overflow its boundary, Floating UI's flip middleware selects a fallback from ['top', 'right', 'bottom', 'left']. Override the fallback list with the fallbackPlacements option.

Responsive placement

The placement value accepts breakpoint prefixes to change direction at different viewport widths. The syntax is the base placement followed by breakpoint:placement tokens, where breakpoints are small, medium, large, xlarge, and 2xlarge. The plugin re-evaluates placement whenever the viewport crosses a registered breakpoint.

<button type="button" class="button secondary"
  data-cx-toggle="popover"
  data-cx-content="Changes with viewport"
  data-cx-placement="top medium:right large:bottom">
top → medium:right → large:bottom
</button>

Advanced features

The popover plugin supports HTML content, focus-based dismissal, and a wrapper pattern for attaching popovers to disabled elements.

HTML content

Set data-cx-html="true" to render HTML tags inside the title and body. Content passes through the built-in sanitizer unless a custom sanitizeFn is provided. Use plain text for any content derived from user input.

<button type="button" class="button primary"
  data-cx-toggle="popover"
  data-cx-title="<em>Formatted</em> title"
  data-cx-content="Body with <strong>bold</strong> text."
  data-cx-html="true">
HTML content
</button>

Focus-based dismissal

Set data-cx-trigger="focus" to dismiss the popover when the trigger loses focus — useful for contextual help that closes as soon as the user moves on.

<a tabindex="0" class="button primary" href="#"
  data-cx-toggle="popover"
  data-cx-trigger="focus"
  data-cx-title="Dismissible popover"
  data-cx-content="Loses focus to dismiss.">
Dismissible popover
</a>

Disabled elements

Disabled elements do not receive click or focus events. Wrap a disabled element in a <span>, place the popover attributes on the wrapper, and add tabindex="0" to keep the wrapper reachable by keyboard.

<span class="d-inline-block" tabindex="0"
  data-cx-toggle="popover"
  data-cx-trigger="hover focus"
  data-cx-content="Attached to the wrapper.">
<button class="button primary" type="button" disabled>Disabled button</button>
</span>

Container

When a parent's stacking context or overflow clips the popover, pass a container option to append the generated element to a different DOM node. Setting container to document.body is common for popovers inside complex layouts:

import { Popover } from '@chassis-ui/css'

new Popover(document.querySelector('.my-trigger'), { container: document.body })

For popovers inside a <dialog>, set container to the dialog element to keep stacking context and focus management correct:

new Popover(document.querySelector('.dialog-trigger'), {
  container: document.querySelector('dialog')
})

Theming

Override popover appearance by assigning a custom class with data-cx-custom-class and redefining the component's custom properties on that class.

.custom-popover {
  --cx-popover-max-width: 200px;
  --cx-popover-border-color: var(--cxd-subtle-bg);
  --cx-popover-header-bg: var(--cxd-subtle-bg);
  --cx-popover-header-color: var(--cx-white);
  --cx-popover-body-padding-x: 1rem;
  --cx-popover-body-padding-y: .5rem;
}

<button type="button" class="button secondary"
  data-cx-toggle="popover"
  data-cx-placement="right"
  data-cx-custom-class="custom-popover"
  data-cx-title="Custom popover"
  data-cx-content="Themed via CSS custom properties.">
Custom popover
</button>

Accessibility

The Popover plugin manages aria-describedby automatically: the trigger element receives an aria-describedby pointing at the generated popover's id while the popover is visible, and the attribute is removed on hide. The generated element carries role="tooltip".

If a trigger has a native title attribute, the plugin moves it to data-cx-original-title on initialization — suppressing the browser's built-in tooltip and using it as the popover's header when data-cx-title is not set.

The default trigger is click. Pressing Enter or Space on a focusable trigger fires the click event, so keyboard users can open and close popovers without additional configuration. Apply popovers only to natively interactive elements — buttons and links — that already receive keyboard focus.

JavaScript API

The Popover plugin extends Tooltip and inherits its full interface. Floating UI must be available, either via the bundled distribution or an import map. Import the Popover class directly:

import { Popover } from '@chassis-ui/css'

Triggers

The data-attribute API initializes and configures popovers without writing JavaScript. The plugin reads all data-cx-* attributes on the trigger element:

Initialization

Instantiate a Popover explicitly when programmatic API access is needed before the first user interaction:

import { Popover } from '@chassis-ui/css'

const popover = new Popover(document.getElementById('myTrigger'), {
  placement: 'top',
  trigger: 'hover focus'
})

const popover = new Popover('#example', {
  boundary: document.body
})

Methods

The following methods are available on each Popover instance:

setContent accepts an object keyed by selector within the popover template. Recognized keys are .popover-header and .popover-body. Each value may be a string, Element, function, or null:

import { Popover } from '@chassis-ui/css'

const popover = Popover.getInstance('#myTrigger')

popover.setContent({
  '.popover-header': 'Updated title',
  '.popover-body': 'Updated content'
})

Options

Options are set via data-cx-* attributes or passed to the constructor as an object. Attribute names use the kebab-case form of the option name — data-cx-custom-class, not data-cx-customClass. Attribute values are parsed to their native types:"true" → true, "0" → 0, and valid JSON strings to objects.

Use data-cx-config to pass multiple options as a JSON string:data-cx-config='{"delay":200}'. Individual data-cx-* attributes take precedence over data-cx-config. You can also use JSON values in individual attributes, such as data-cx-delay='{"show":100,"hide":200}'.

When initializing components, Chassis merges configurations from multiple sources in this priority order: default settings, data-cx-config values, individual data-cx-*attributes, and finally any JavaScript object options. Values defined later in this sequence override earlier ones.

floatingConfig function

When floatingConfig is a function, it receives the default Floating UI configuration object and must return a new config:

import { Popover } from '@chassis-ui/css'

const popover = new Popover(element, {
  floatingConfig(defaultConfig) {
    return { ...defaultConfig, strategy: 'fixed' }
  }
})

Events

Each lifecycle transition fires a namespaced event on the trigger element:

import { Popover } from '@chassis-ui/css'

const trigger = document.getElementById('myTrigger')

trigger.addEventListener('hidden.cx.popover', () => {
  Popover.getInstance(trigger).dispose()
})

CSS

The Popover component can be customized at both runtime (via custom properties) and compile time (via Sass variables).

Custom properties

The Popover component exposes CSS custom properties to control its appearance at runtime.

--zindex: var(--popover-zindex, #{$zindex-popover});
--max-width: var(--popover-max-width, #{$popover-max-width});
@include map-font($popover-font, popover);
--fg-color: var(--popover-fg-color, #{$popover-fg-color});
--bg-color: var(--popover-bg-color, #{$popover-bg-color});
--border-width: var(--popover-border-width, #{$popover-border-width});
--border-color: var(--popover-border-color, #{$popover-border-color});
--border-radius: var(--popover-border-radius, #{$popover-border-radius});
--inner-border-radius: var(--popover-inner-border-radius, #{$popover-inner-border-radius});
--box-shadow: var(--popover-box-shadow, #{$popover-box-shadow});
--header-padding-x: var(--popover-padding-x, #{$popover-header-padding-x});
--header-padding-y: var(--popover-padding-y, #{$popover-header-padding-y});
@include map-font($popover-header-font, popover-header, header);
--header-fg-color: var(--popover-header-fg-color, #{$popover-header-fg-color});
--header-bg-color: var(--popover-header-bg-color, #{$popover-header-bg-color});
--body-padding-x: var(--popover-body-padding-x, #{$popover-body-padding-x});
--body-padding-y: var(--popover-body-padding-y, #{$popover-body-padding-y});
--body-color: var(--popover-body-color, #{$popover-body-color});
--arrow-width: var(--popover-arrow-width, #{$popover-arrow-width});
--arrow-height: var(--popover-arrow-height, #{$popover-arrow-height});
--arrow-border: var(--popover-arrow-border, var(--border-color));

Sass variables

The Popover component uses Sass variables in scss/config/_defaults.scss to define its defaults.

$popover-font:                      $font-text-medium-normal;
$popover-fg-color:                  var(--fg-main);
$popover-bg-color:                  var(--bg-main);
$popover-max-width:                 17.25rem; //276px;
$popover-border-width:              var(--border-width-medium);
$popover-border-color:              var(--border-subtle);
$popover-border-radius:             var(--border-radius-medium);
$popover-inner-border-radius:       calc(#{$popover-border-radius} - #{$popover-border-width});
$popover-box-shadow:                var(--box-shadow-medium);

$popover-header-font:               $font-text-medium-strong;
$popover-header-fg-color:           var(--fg-main);
$popover-header-bg-color:           var(--bg-even);
$popover-header-padding-y:          var(--space-xsmall);
$popover-header-padding-x:          var(--space-medium);

$popover-body-color:                var(--fg-color);
$popover-body-padding-y:            var(--space-small);
$popover-body-padding-x:            var(--space-medium);

$popover-arrow-width:               1rem;
$popover-arrow-height:              .5rem;