Popover

Use it for secondary forms, filters, or actions that should stay in context without navigating away. It uses Blue Yonder surface styling and portals through ThemeProvider so the panel renders in the correct container.

Unlike HoverCard, which reveals content on hover, Popover is intended for explicit open/close interaction and can host interactive controls such as Input, Button, or Label.

Installation

The component is exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use the following composition to build a Popover:

Popover
├── PopoverTrigger
├── PopoverAnchor (optional)
└── PopoverContent

PopoverContent already wraps the panel in a portal that targets the ThemeProvider container, so you typically render it directly without a separate portal. Behavior follows Radix Popover.

Usage

import {
  Button,
  Input,
  Label,
  Popover,
  PopoverContent,
  PopoverTrigger,
} from '@by/experience-system';

Popover and its parts are client components ('use client'). Wrap your tree in ThemeProvider so PopoverContent can resolve the portal container. Use them inside a Client Component or a dynamic import when using the Next.js App Router.

<Popover>
  <PopoverTrigger asChild>
    <Button>Open popover</Button>
  </PopoverTrigger>
  <PopoverContent className="w-80">
    <div className="grid gap-4">
      <div className="space-y-2">
        <h4 className="text-lg leading-none font-medium">Dimensions</h4>
        <p className="text-sm text-neutral-11">Set the dimensions for the layer.</p>
      </div>
      <div className="grid grid-cols-3 items-center gap-4">
        <Label htmlFor="width">Width</Label>
        <Input id="width" defaultValue="100%" className="col-span-2 h-8" />
      </div>
    </div>
  </PopoverContent>
</Popover>

When to use

• Compact tasks next to a control (dimensions, filters, quick edits) where a full-page or Dialog would feel heavy.
• Optional detail that should not clutter the default layout until the user asks for it.
• Touch and keyboard flows where hover is not reliable—popover uses explicit activation like DropdownMenu, not pointer hover.

When not to use

• Blocking or critical flows that must capture full attention—prefer Dialog or Drawer with clear primary actions.
• Hover-only previews—use HoverCard or Tooltip when the content is read-only and hover is acceptable for your audience.
• Long scrolling forms or dense multi-step content—use a dedicated page or larger overlay surface.

API Reference

Pieces map to Radix UI Popover primitives. The tables below mirror the upstream API in full; styling, motion, and the portal container come from @by/experience-system and ThemeProvider.

Popover

Popover contains all the parts of a popover. Exported as Popover; forwards Popover.Root props from radix-ui.

PopoverTrigger

PopoverTrigger — the control that toggles the popover. Use asChild to merge props into a Button or other focusable element.

PopoverAnchor

PopoverAnchor — optional element to position the panel against. Use it when alignment should reference something other than the trigger (for example, anchoring to a row or input while the trigger lives elsewhere).

PopoverContent

PopoverContent — the floating panel that opens from the trigger. This export wraps Popover.Portal with the Experience System container from useContainerElement(), so you typically render PopoverContent directly without a separate PopoverPortal. Default classes provide border, shadow, padding, and enter/exit motion.

@by/experience-system does not currently re-export PopoverPortal, PopoverClose, or PopoverArrow. If you need them, import them from radix-ui directly; for the full primitive reference and any upstream updates, see the Radix docs.

Accessibility

Use a real control for PopoverTrigger (for example Button or Link) so keyboard users can focus it and open the panel per Radix — accessibility. Keep focus order predictable inside PopoverContent when it contains fields or actions, and provide an explicit dismiss path (close button, primary action, or onOpenChange) when the panel is non-modal.

Keyboard interactions

Source in the repo: packages/experience-system/src/components/Popover/Popover.tsx. Agent-oriented contracts: packages/experience-system/src/components/Popover/Popover.instructions.md.