Popovers

Introduction

Popovers in Chassis CSS provide rich contextual overlays that display detailed information, forms, or interactive content without leaving the current page context. Built on modern web standards with intelligent positioning via Popper.js, popovers integrate seamlessly with your design system while maintaining accessibility and performance excellence.

Unlike simple tooltips, popovers support complex content including headers, body sections, and interactive elements. The positioning system automatically handles viewport constraints and collision detection, while the component architecture ensures consistent behavior across devices and screen sizes.

Chassis CSS popovers operate on explicit initialization for optimal performance:

• Manual initialization prevents overhead on unused elements
• Intelligent positioning powered by Popper.js with automatic placement adjustment
• Comprehensive event integration for application logic and user interaction
• Accessibility through proper ARIA attributes and keyboard navigation support
• CSS custom properties enable seamless theming and brand consistency

Implementation requirements

Before implementing popovers, ensure these dependencies and considerations are addressed:

• Include popper.min.js before chassis.js, or use chassis.bundle.min.js
• Popovers with empty title and content values will not display
• Hidden elements cannot trigger popovers
• Use container: 'body' for complex component layouts (input groups, button groups)
• Apply popovers only to keyboard-focusable, interactive elements for accessibility compliance
• Hide popovers before removing their trigger elements from the DOM
• Specify explicit containers for popovers within modal dialogs to ensure proper focus management

Examples

Explore practical popover implementations demonstrating initialization patterns, positioning strategies, and customization techniques. These examples showcase Chassis CSS's flexible popover system across various use cases.

Initialization patterns

Initialize popovers via JavaScript before they can be used. Select elements by their data-cx-toggle attribute for batch initialization:

const popoverTriggerList = document.querySelectorAll('[data-cx-toggle="popover"]')
const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new chassis.Popover(popoverTriggerEl))

Interactive demonstration

This example demonstrates a fully functional popover with title and body content. Titles are set via data-cx-title and body content via data-cx-content.

<button type="button" class="button large danger" data-cx-toggle="popover" data-cx-title="Popover title" data-cx-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

Positioning system

Chassis CSS supports four directional placements with automatic RTL adaptation. Set data-cx-placement to control popover direction with intelligent fallback positioning.

<button type="button" class="button secondary" data-cx-container="body" data-cx-toggle="popover" data-cx-placement="top" data-cx-content="Top popover">
  Popover on top
</button>
<button type="button" class="button secondary" data-cx-container="body" data-cx-toggle="popover" data-cx-placement="right" data-cx-content="Right popover">
  Popover on right
</button>
<button type="button" class="button secondary" data-cx-container="body" data-cx-toggle="popover" data-cx-placement="bottom" data-cx-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="button secondary" data-cx-container="body" data-cx-toggle="popover" data-cx-placement="left" data-cx-content="Left popover">
  Popover on left
</button>

Container control

When parent elements interfere with popover positioning, specify a custom container to control where the popover appears in the DOM:

const popover = new chassis.Popover('.example-popover', {
  container: 'body'
})

For popovers within modal dialogs, set the container to the modal to ensure proper focus management and interaction:

const popover = new chassis.Popover('.example-popover', {
  container: '.modal-content'
})

Custom appearance

Customize popover appearance using CSS custom properties. Apply custom classes with data-cx-custom-class="custom-popover" to scope styling and override CSS variables for brand-specific theming.

.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="This popover is themed via CSS variables.">
  Custom popover
</button>

Focus-based dismissal

Use the focus trigger to dismiss popovers when users interact with other elements, ideal for contextual help and secondary information.

<a tabindex="0" class="button large danger" role="button" data-cx-toggle="popover" data-cx-trigger="focus" data-cx-title="Dismissible popover" data-cx-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>

const popover = new chassis.Popover('.popover-dismiss', {
  trigger: 'focus'
})

Disabled elements

Elements with the disabled attribute cannot trigger popovers directly. Use a wrapper element with tabindex="0" to enable popover functionality while maintaining accessibility:

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

CSS

Customize popover appearance and behavior through Chassis CSS's comprehensive styling system, featuring CSS custom properties and Sass variables for design system integration.

This component can be customized using CSS variables, allowing for styles to be modified dynamically on the page. These CSS variables are part of Chassis CSS's design token system, giving design teams control over component appearance. See the design tokens page for more details.

Custom properties

Chassis CSS popovers utilize CSS custom properties for runtime customization and design token integration. Local CSS variables on .popover enable dynamic theming while maintaining backward compatibility.

These CSS variables control the component's appearance and can be modified dynamically on the page. Components use cascading variables, allowing seamless variations in size, color, and style without redundant style declarations through component inheritance and the context class system.

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

Sass variables

Design system integration through Sass variables provides comprehensive popover customization for build-time theming and brand alignment.

These Sass variables are also exposed as CSS custom properties using the --cx- prefix. A Sass variable $variable-name becomes available as --cx-variable-name in CSS, allowing for styles to be modified dynamically on the page. See the context components page for more details.

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

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

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

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

JavaScript API

Control popover behavior programmatically with Chassis CSS's comprehensive JavaScript interface, featuring dynamic content generation, intelligent positioning, and accessibility features.

Initialization

The popover plugin generates content and markup on demand, placing popovers relative to their trigger elements for optimal performance and accessibility. Initialize popovers via JavaScript:

const exampleEl = document.getElementById('example')
const popover = new chassis.Popover(exampleEl, options)

Data attributes

Individual popover options can be specified through data attributes for declarative configuration without JavaScript initialization.

Popovers require minimal markup while generating semantic HTML with proper ARIA attributes for optimal accessibility and screen reader support. The required markup for a popover is only a data attribute and content attributes on the HTML element:

<!-- HTML to write -->
<button type="button" data-cx-toggle="popover" data-cx-title="Popover title" data-cx-content="Amazing content here">Click me</button>

<!-- Generated markup by the plugin -->
<div class="popover cx-popover-auto" role="tooltip">
  <div class="popover-arrow"></div>
  <h3 class="popover-header">Popover title</h3>
  <div class="popover-body">Amazing content here</div>
</div>

Configuration options

Customize popover behavior through JavaScript options or HTML data attributes for flexible integration with your application logic.

Chassis components offer flexible configuration through both data attributes and JavaScript. To use data attributes, prefix any option with data-cx- followed by the option name in kebab-case format (using hyphens instead of camelCase). For example, write data-cx-custom-class="my-class" rather than data-cx-customClass="my-class".

For more complex configurations, Chassis provides the data-cx-config attribute which accepts a JSON string of multiple settings. This approach simplifies markup when configuring several options at once. If the same option appears in both data-cx-config and as a separate data attribute (like data-cx-title), the individual attribute takes precedence. You can also use JSON values in individual attributes, such as data-cx-delay='{"show":100,"hide":200}' for more granular control.

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.

Popper configuration

Advanced Popper.js configuration can be customized through a function that receives the default Chassis CSS configuration and returns a modified configuration object.

const popover = new chassis.Popover(element, {
  popperConfig(defaultCxPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultCxPopperConfig if needed...
    // return newPopperConfig
  }
})

Methods

Chassis CSS provides a comprehensive set of methods for programmatic popover control, enabling dynamic content updates and lifecycle management.

const popover = chassis.Popover.getInstance('#example') // Returns a Chassis CSS popover instance

// setContent example
popover.setContent({
  '.popover-header': 'another title',
  '.popover-body': 'another content'
})

Events

Listen to popover lifecycle events to integrate with your application logic and create responsive user interactions.

const myPopoverTrigger = document.getElementById('myPopover')
const popover = chassis.Popover.getOrCreateInstance(myPopoverTrigger)

myPopoverTrigger.addEventListener('hidden.cx.popover', () => {
  // do something...
})

popover.hide()