Popover

v1.0.9

Documentation Under Review

The Popover component is built on top of Radix UI's Popover primitive. It provides a click-triggered overlay that displays rich content and interactive elements. The product variant supports custom styling for branded applications.

Installation

npm install @pmi/catalyst-popover

Tailwind Config

The Popover package comes with a Tailwind preset that provides entrance animations for the component. Import this into your Tailwind configuration and add the preset to the presets array.

import type { Config } from 'tailwindcss';
import { default as tailwindPopoverPreset } from '@pmi/catalyst-popover/tailwind.config';

export default {
  content: ['./src/**/*.{ts,tsx,js,jsx}', './node_modules/@pmi/catalyst-*/**/*.{ts,tsx,js,jsx}'],
  theme: {},
  presets: [tailwindPopoverPreset],
  plugins: [],
} satisfies Config;

The preset includes:

• Animations: Smooth slide and fade animations from all four directions
• Keyframes: slideDownAndFade, slideUpAndFade, slideLeftAndFade, slideRightAndFade
• Timing: 400ms cubic-bezier easing for smooth motion

Note: These are the same animations used by the Tooltip component.

Usage

import {
  PopoverRoot,
  PopoverTrigger,
  PopoverContent,
  PopoverArrow,
} from '@pmi/catalyst-popover';

<PopoverRoot>
  <PopoverTrigger>Click me</PopoverTrigger>
  <PopoverContent>
    Popover content
    <PopoverArrow />
  </PopoverContent>
</PopoverRoot>

Popover vs Tooltip

Examples

Basic Popover

A simple click-triggered popover with text content.

Positioning

Control popover placement using side and align props.

With Icon Trigger

Use icons as popover triggers for compact UI elements.

Complex Content

Popovers can contain rich content including lists and formatted text.

With Portal

Render popover content in a portal outside the DOM hierarchy for better z-index control.

Custom Styling

Apply custom color palette for product-specific branded designs.

API Reference

PopoverRoot

The root component that manages popover state.

PopoverTrigger

The button that opens the popover.

PopoverContent

The popover content that appears.

PopoverPortal

Renders the popover content in a portal (outside the DOM hierarchy).

PopoverArrow

An optional arrow element that points to the trigger.

PopoverAnchor

An optional element to position the popover against.

PopoverClose

An optional button to close the popover.

Accessibility

The Popover component follows WAI-ARIA best practices:

• Keyboard Navigation: Popovers open on click and can be navigated with Tab
• Escape Key: Pressing Escape dismisses the popover
• Focus Management: Focus can be managed within the popover content
• ARIA Attributes: Automatically applies proper aria-expanded and aria-controls
• Screen Readers: Content is announced when the popover opens
• Focus Trap: Optional modal mode traps focus within popover

Best Practices

1. Click-Triggered: Popovers are click-triggered (use Tooltip for hover)
2. Interactive Content: Use for forms, menus, or actionable content
3. Close Mechanisms: Provide clear ways to close (outside click, Escape, close button)
4. Focus Management: Add tabIndex={0} to content elements for keyboard navigation
5. Avoid Nesting: Don't nest popovers within popovers
6. Mobile Friendly: Ensure touch targets are large enough (minimum 44×44px)
7. Custom Colors: When using custom styling, maintain sufficient contrast ratios (WCAG AA)

Related Components

• Tooltip - Hover-triggered overlay for supplementary info
• Dialog - Modal overlay for critical actions
• DropdownMenu - Menu-specific overlay