or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-spectrum-css--popover

The Spectrum CSS popover component providing floating content containers with positioning, animations, and optional pointer tips.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@spectrum-css/popover@8.2.x

To install, run

npx @tessl/cli install tessl/npm-spectrum-css--popover@8.2.0

Spectrum CSS Popover

Spectrum CSS Popover is a floating content container component that provides consistent positioning, animations, and visual styling for tooltips, dropdown menus, context menus, and modal-like interfaces. It supports comprehensive positioning options, optional pointer tips, theming variants, and full RTL/LTR internationalization support as part of Adobe's Spectrum Design System.

Package Information

Package Name: @spectrum-css/popover
Package Type: npm
Language: CSS
Installation: npm install @spectrum-css/popover

Core Imports

/* Main popover styles (includes spectrum-two theme by default) */
@import "@spectrum-css/popover/index.css";

/* Alternative theme variants (optional) */
@import "@spectrum-css/popover/themes/spectrum.css";      /* Legacy Spectrum theme */
@import "@spectrum-css/popover/themes/express.css";       /* Express theme (borderless) */

CDN usage:

<link rel="stylesheet" href="https://unpkg.com/@spectrum-css/popover@8.2.0/dist/index.css">
<!-- Optional: Override default theme with legacy or express -->
<link rel="stylesheet" href="https://unpkg.com/@spectrum-css/popover@8.2.0/dist/themes/express.css">

Basic Usage

<!-- Basic popover -->
<div class="spectrum-Popover is-open" role="presentation">
  <p>Popover content goes here</p>
</div>

<!-- Popover with tip pointer -->
<div class="spectrum-Popover spectrum-Popover--withTip spectrum-Popover--bottom is-open" role="presentation">
  <p>Content with tip pointing up</p>
  <svg class="spectrum-Popover-tip" viewBox="0 -0.5 16 9" width="10">
    <path class="spectrum-Popover-tip-triangle" d="M-1,-1 8,8 17,-1"></path>
  </svg>
</div>

<!-- Positioned popover with alignment -->
<div class="spectrum-Popover spectrum-Popover--withTip spectrum-Popover--top-left is-open" role="presentation">
  <p>Positioned above trigger, left-aligned</p>
  <svg class="spectrum-Popover-tip" viewBox="0 -0.5 16 9" width="10">
    <path class="spectrum-Popover-tip-triangle" d="M-1,-1 8,8 17,-1"></path>
  </svg>
</div>

Architecture

The Spectrum CSS Popover component consists of several key architectural layers:

Base Component: .spectrum-Popover provides core styling, positioning, theming, and animation foundation
State Management: .is-open class controls visibility and triggers directional animations
Positioning System: Modifier classes control popover placement relative to trigger elements (top, bottom, left, right, start, end)
Tip System: Optional triangular pointer with SVG-based rendering and intelligent positioning
Theme Variants: Multiple design themes (Spectrum, Express) with different visual characteristics
Internationalization: Full RTL/LTR support using logical positioning properties
Customization Layer: CSS custom properties enabling extensive theming and behavioral customization

Capabilities

Base Popover Class

The foundational popover container with core styling and behavior.

.spectrum-Popover {
  /* Core popover styling with absolute positioning, flexbox layout, theming */
  /* Includes border, background, shadow, corner radius, and content padding */
  /* Provides CSS custom property integration for theming and customization */
}

Open State

Controls popover visibility and animation states.

.spectrum-Popover.is-open {
  /* Makes popover visible and triggers directional animation */
  /* Animation direction depends on position modifier class */
  /* Uses CSS transforms for smooth animation transitions */
}

Tip Variants

Enables triangular pointer tips that connect popovers to their trigger elements.

.spectrum-Popover--withTip {
  /* Enables overflow:visible for tip rendering */
  /* Adds margin spacing to account for tip dimensions */
  /* Provides tip positioning and styling foundation */
}

.spectrum-Popover-tip {
  /* SVG container for triangular pointer */
  /* Absolutely positioned based on popover placement */
  /* Size controlled by --spectrum-popover-pointer-width/height */
}

.spectrum-Popover-tip-triangle {
  /* SVG path element creating triangular shape */
  /* Fill matches popover background color */
  /* Stroke matches popover border color and width */
}

Primary Positioning

Core directional positioning relative to trigger elements.

.spectrum-Popover--top {
  /* Positions popover above trigger element */
  /* Animates upward when opened with is-open class */
  /* Includes margin spacing for tip when combined with --withTip */
}

.spectrum-Popover--bottom {
  /* Positions popover below trigger element */
  /* Animates downward when opened with is-open class */
  /* Includes margin spacing for tip when combined with --withTip */
}

.spectrum-Popover--left {
  /* Positions popover to left of trigger element */
  /* Animates leftward when opened with is-open class */
  /* Fixed directional positioning, not affected by text direction */
}

.spectrum-Popover--right {
  /* Positions popover to right of trigger element */
  /* Animates rightward when opened with is-open class */
  /* Fixed directional positioning, not affected by text direction */
}

Logical Positioning

Internationalization-aware positioning that adapts to text direction.

.spectrum-Popover--start {
  /* Logical start positioning (left in LTR, right in RTL) */
  /* Direction-aware animations for international layouts */
  /* Animates toward logical start when opened */
}

.spectrum-Popover--end {
  /* Logical end positioning (right in LTR, left in RTL) */
  /* Direction-aware animations for international layouts */
  /* Animates toward logical end when opened */
}

Alignment Variants

Compound positioning classes for precise popover alignment relative to triggers.

.spectrum-Popover--top-left {
  /* Popover above trigger, left-aligned */
  /* Tip positioned at left side when using --withTip */
}

.spectrum-Popover--top-right {
  /* Popover above trigger, right-aligned */
  /* Tip positioned at right side when using --withTip */
}

.spectrum-Popover--top-start {
  /* Popover above trigger, logical start-aligned */
  /* RTL/LTR aware tip positioning */
}

.spectrum-Popover--top-end {
  /* Popover above trigger, logical end-aligned */
  /* RTL/LTR aware tip positioning */
}

.spectrum-Popover--bottom-left {
  /* Popover below trigger, left-aligned */
  /* Tip positioned at left side when using --withTip */
}

.spectrum-Popover--bottom-right {
  /* Popover below trigger, right-aligned */
  /* Tip positioned at right side when using --withTip */
}

.spectrum-Popover--bottom-start {
  /* Popover below trigger, logical start-aligned */
  /* RTL/LTR aware tip positioning */
}

.spectrum-Popover--bottom-end {
  /* Popover below trigger, logical end-aligned */
  /* RTL/LTR aware tip positioning */
}

.spectrum-Popover--left-top {
  /* Popover left of trigger, top-aligned */
  /* Tip positioned at top when using --withTip */
}

.spectrum-Popover--left-bottom {
  /* Popover left of trigger, bottom-aligned */
  /* Tip positioned at bottom when using --withTip */
}

.spectrum-Popover--right-top {
  /* Popover right of trigger, top-aligned */
  /* Tip positioned at top when using --withTip */
}

.spectrum-Popover--right-bottom {
  /* Popover right of trigger, bottom-aligned */
  /* Tip positioned at bottom when using --withTip */
}

.spectrum-Popover--start-top {
  /* Popover at logical start, top-aligned */
  /* RTL/LTR aware positioning and tip placement */
}

.spectrum-Popover--start-bottom {
  /* Popover at logical start, bottom-aligned */
  /* RTL/LTR aware positioning and tip placement */
}

.spectrum-Popover--end-top {
  /* Popover at logical end, top-aligned */
  /* RTL/LTR aware positioning and tip placement */
}

.spectrum-Popover--end-bottom {
  /* Popover at logical end, bottom-aligned */
  /* RTL/LTR aware positioning and tip placement */
}

CSS Custom Properties

Animation Properties

Control popover animation behavior and timing.

--spectrum-popover-animation-distance {
  /* Distance popover moves during open/close animation */
  /* Default: var(--spectrum-spacing-100) */
  /* Affects both visual movement and spacing calculations */
}

Overlay Animation Properties

Control overlay-based animation timing (inherited from commons/overlay.css).

--spectrum-overlay-animation-duration {
  /* Duration for opening animation */
  /* Default: var(--spectrum-animation-duration-100) */
  /* Inherited from %spectrum-overlay mixin */
}

--spectrum-overlay-animation-duration-opened {
  /* Duration for closing animation */
  /* Default: var(--spectrum-animation-duration-0) */
  /* Inherited from %spectrum-overlay mixin */
}

Visual Appearance Properties

Control popover visual styling and theming.

--spectrum-popover-background-color {
  /* Background color of popover content area */
  /* Default: var(--spectrum-background-layer-2-color) */
  /* Applied to main popover container and tip fill */
}

--spectrum-popover-border-color {
  /* Border color around popover perimeter */
  /* Default: var(--spectrum-gray-400) */
  /* Applied to container border and tip stroke */
}

--spectrum-popover-border-width {
  /* Width of popover border */
  /* Default: var(--spectrum-border-width-100) (spectrum-two theme) */
  /* Default: 0 (express theme for borderless appearance) */
  /* Set via theme files, not directly in main CSS */
}

--spectrum-popover-corner-radius {
  /* Border radius for rounded corners */
  /* Default: var(--spectrum-corner-radius-100) */
  /* Affects visual appearance and tip edge offset calculations */
}

Spacing Properties

Control internal and external spacing.

--spectrum-popover-content-area-spacing-vertical {
  /* Vertical padding inside popover content area */
  /* Default: var(--spectrum-popover-top-to-content-area) */
  /* Provides consistent internal spacing for content */
}

Shadow Properties

Control drop shadow appearance for depth and elevation.

--spectrum-popover-shadow-horizontal {
  /* Horizontal offset for drop shadow */
  /* Default: var(--spectrum-drop-shadow-x) */
}

--spectrum-popover-shadow-vertical {
  /* Vertical offset for drop shadow */
  /* Default: var(--spectrum-drop-shadow-y) */
}

--spectrum-popover-shadow-blur {
  /* Blur radius for drop shadow */
  /* Default: var(--spectrum-drop-shadow-blur) */
}

--spectrum-popover-shadow-color {
  /* Color of drop shadow */
  /* Default: var(--spectrum-drop-shadow-color) */
}

Tip Properties

Control triangular pointer tip dimensions and positioning.

--spectrum-popover-pointer-width {
  /* Width of triangular tip pointer */
  /* Default: var(--spectrum-popover-tip-width) */
  /* Used for tip sizing and margin calculations */
}

--spectrum-popover-pointer-height {
  /* Height of triangular tip pointer */
  /* Default: var(--spectrum-popover-tip-height) */
  /* Used for tip sizing and margin calculations */
}

--spectrum-popover-pointer-edge-offset {
  /* Default distance from popover edge to tip center */
  /* Default: calc(var(--spectrum-corner-radius-100) + (var(--spectrum-popover-tip-width) / 2)) */
  /* Calculated to account for corner radius and tip centering */
}

--spectrum-popover-pointer-edge-spacing {
  /* Distance from edge when centering tip to source element */
  /* Default: calc(var(--spectrum-popover-pointer-edge-offset) - (var(--spectrum-popover-tip-width) / 2)) */
  /* Override to center tip on specific trigger element */
}

Modifier Properties

Override any component property for customization.

--mod-popover-animation-distance     /* Override animation distance */
--mod-popover-background-color       /* Override background color */
--mod-popover-border-color           /* Override border color */
--mod-popover-border-width           /* Override border width */
--mod-popover-content-area-spacing-vertical  /* Override content padding */
--mod-popover-corner-radius          /* Override corner radius */
--mod-popover-filter                 /* Override drop shadow filter */
--mod-popover-pointer-edge-spacing   /* Override tip edge spacing */
--mod-popover-pointer-height         /* Override tip height */
--mod-popover-pointer-width          /* Override tip width */
--mod-popover-shadow-blur            /* Override shadow blur */
--mod-popover-shadow-color           /* Override shadow color */
--mod-popover-shadow-horizontal      /* Override shadow horizontal offset */
--mod-popover-shadow-vertical        /* Override shadow vertical offset */
--mod-overlay-animation-duration     /* Override overlay opening animation duration */
--mod-overlay-animation-duration-opened  /* Override overlay closing animation duration */

High Contrast Properties

Accessibility enhancements for forced-colors mode.

--highcontrast-popover-border-color {
  /* Border color override for Windows high contrast mode */
  /* Default: CanvasText */
  /* Automatically applied when (forced-colors: active) */
}

Usage Examples

Basic Tooltip

<!-- Simple tooltip above element -->
<div class="spectrum-Popover spectrum-Popover--withTip spectrum-Popover--top is-open">
  <p>This is a tooltip message</p>
  <svg class="spectrum-Popover-tip" viewBox="0 -0.5 16 9" width="10">
    <path class="spectrum-Popover-tip-triangle" d="M-1,-1 8,8 17,-1"></path>
  </svg>
</div>

Dropdown Menu

<!-- Dropdown menu below button -->
<div class="spectrum-Popover spectrum-Popover--bottom-start is-open">
  <div class="spectrum-Menu">
    <div class="spectrum-Menu-item">Option 1</div>
    <div class="spectrum-Menu-item">Option 2</div>
    <div class="spectrum-Menu-item">Option 3</div>
  </div>
</div>

Context Menu with Tip

<!-- Context menu with pointer tip -->
<div class="spectrum-Popover spectrum-Popover--withTip spectrum-Popover--right-top is-open">
  <div class="spectrum-Menu">
    <div class="spectrum-Menu-item">Cut</div>
    <div class="spectrum-Menu-item">Copy</div>
    <div class="spectrum-Menu-item">Paste</div>
  </div>
  <!-- Note: Right/left positioning uses rotated viewBox dimensions (9x16) -->
  <svg class="spectrum-Popover-tip" viewBox="0 -0.5 9 16" width="10">
    <path class="spectrum-Popover-tip-triangle" d="M-1,-1 8,8 -1,17"></path>
  </svg>
</div>

Custom Styled Popover

<div class="spectrum-Popover spectrum-Popover--withTip spectrum-Popover--bottom is-open" 
     style="--mod-popover-background-color: #1e1e1e; --mod-popover-border-color: #333; --mod-popover-shadow-color: rgba(0,0,0,0.5);">
  <p style="color: white;">Dark themed popover</p>
  <svg class="spectrum-Popover-tip" viewBox="0 -0.5 16 9" width="10">
    <path class="spectrum-Popover-tip-triangle" d="M-1,-1 8,8 17,-1"></path>
  </svg>
</div>

Centered Tip on Small Trigger

<!-- Custom tip positioning for precise alignment -->
<div class="spectrum-Popover spectrum-Popover--withTip spectrum-Popover--top is-open"
     style="--mod-popover-pointer-edge-spacing: 20px;">
  <p>Tip centered on 40px wide button</p>
  <svg class="spectrum-Popover-tip" viewBox="0 -0.5 16 9" width="10">
    <path class="spectrum-Popover-tip-triangle" d="M-1,-1 8,8 17,-1"></path>
  </svg>
</div>

RTL Layout Support

<!-- Logical positioning for international layouts -->
<div dir="rtl">
  <div class="spectrum-Popover spectrum-Popover--withTip spectrum-Popover--start is-open">
    <p>هذا محتوى النافذة المنبثقة</p>
    <svg class="spectrum-Popover-tip" viewBox="0 -0.5 9 16" width="10">
      <path class="spectrum-Popover-tip-triangle" d="M-1,-1 8,8 -1,17"></path>
    </svg>
  </div>
</div>

Theming Integration

Default Theme (Spectrum-Two)

The main index.css imports spectrum-two.css by default, which sets:

/* Included automatically in index.css */
--spectrum-popover-border-width: var(--spectrum-border-width-100);

Express Theme (Borderless)

Override the default theme for borderless popovers:

@import "@spectrum-css/popover/index.css";
@import "@spectrum-css/popover/themes/express.css";

/* Express theme automatically sets --spectrum-popover-border-width: 0 */
/* Results in borderless popovers with shadow-only elevation */

Legacy Theme (Spectrum 1)

Use the legacy Spectrum 1 visual style:

@import "@spectrum-css/popover/index.css";
@import "@spectrum-css/popover/themes/spectrum.css";

/* Legacy theme inherits spectrum-two settings but can be customized */

Custom Theme Integration

@import "@spectrum-css/popover/index.css";

/* Custom theme overrides */
.my-theme .spectrum-Popover {
  --mod-popover-background-color: var(--my-popover-bg);
  --mod-popover-border-color: var(--my-popover-border);
  --mod-popover-shadow-color: var(--my-popover-shadow);
  --mod-popover-corner-radius: var(--my-border-radius);
  --mod-popover-border-width: var(--my-border-width);
}

JavaScript Integration Patterns

While this is a CSS-only component, common JavaScript integration patterns include:

// Show/hide popover
const popover = document.querySelector('.spectrum-Popover');
popover.classList.add('is-open');

// Position popover relative to trigger
function positionPopover(trigger, popover, placement = 'bottom') {
  popover.className = `spectrum-Popover spectrum-Popover--${placement} is-open`;
  // Additional positioning logic would be implemented here
}

// Toggle with animation
function togglePopover(popover) {
  if (popover.classList.contains('is-open')) {
    popover.classList.remove('is-open');
  } else {
    popover.classList.add('is-open');
  }
}

Accessibility Considerations

Use role="presentation" on popover container as shown in examples
Ensure proper focus management when opening/closing
Consider aria-describedby or aria-labelledby relationships with trigger elements
Provide keyboard navigation support (Escape to close, etc.)
Test with screen readers and high contrast mode
The component automatically adapts to Windows high contrast mode via --highcontrast-popover-border-color

Browser Support

Modern browsers supporting CSS custom properties (IE 11+ with polyfills)
CSS Grid and Flexbox support required
SVG support required for tip functionality
Container queries supported where available (progressive enhancement)

Peer Dependencies

The component integrates with related Spectrum CSS components:

@spectrum-css/tokens - Design system tokens (>=16.0.0 <17.0.0, optional)
@spectrum-css/menu - For dropdown menus within popovers (>=9.0.0 <10.0.0, optional)
@spectrum-css/dialog - For dialog content within popovers (>=12.0.0 <13.0.0, optional)
@spectrum-css/alertdialog - For alert dialogs within popovers (>=4.0.0 <5.0.0, optional)
@spectrum-css/divider - For content separation within popovers (>=5.0.0 <6.0.0, optional)

All peer dependencies are optional and only needed when using specific content types within popovers.