Popover

Content Strategy

Keep popover content focused on a single task or group of related settings. Avoid deeply nested layouts or excessive scrolling inside popovers. If the content grows beyond what fits comfortably in a floating panel, consider using a Dialog or Sheet instead. Include a clear heading so users understand the popover's purpose at a glance.

Positioning & Overflow

The popover automatically flips to the opposite side when there is not enough viewport space. Use sideOffset to control the gap between the trigger and the panel (default is 4px). For alignment fine-tuning, combine align with alignOffset. The default width is w-72 (288px); override it with a className when needed.

Trigger Design

Always use asChild on PopoverTrigger to render a styled Button rather than a plain element. The trigger should clearly indicate that it opens additional content, for example by including a chevron icon or descriptive label.

Color & Contrast

The popover surface uses bg-popover with text-popover-foreground for consistent theming across light and dark modes. Borders, shadows, and rounded corners are applied by default. Inner content should continue to use semantic tokens like text-muted-foreground for descriptions and border-border for dividers.

Keyboard Navigation

• Tab — Move focus to the popover trigger
• Enter or Space — Open or close the popover
• Tab — When open, move focus through interactive elements inside the popover
• Escape — Close the popover and return focus to the trigger

Screen Reader Support

• The trigger automatically receives aria-expanded reflecting the open state
• The trigger is linked to the content via aria-controls
• Icon-only triggers require aria-label for screen reader users
• Use aria-describedby for additional context about what the popover contains

Focus Management

When the popover opens, focus moves to the first focusable element inside the content panel. When modal is set to true, focus is trapped within the popover until it is dismissed. On close, focus returns to the trigger element automatically.

Dismiss Behavior

The popover closes when pressing Escape, clicking outside the content, or when another popover opens. In modal mode, only Escape and explicit close actions dismiss the popover.

ARIA Attributes

{/* Standard popover with descriptive trigger */}
<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" aria-label="Edit dimensions">
      <Settings className="size-4" />
    </Button>
  </PopoverTrigger>
  <PopoverContent>
    {/* Interactive content receives focus */}
  </PopoverContent>
</Popover>

{/* Modal popover - traps focus within */}
<Popover modal>
  <PopoverTrigger asChild>
    <Button>Open modal popover</Button>
  </PopoverTrigger>
  <PopoverContent>
    {/* Focus is trapped until popover is dismissed */}
  </PopoverContent>
</Popover>

{/* Popover with explicit description */}
<Popover>
  <PopoverTrigger asChild>
    <Button aria-describedby="filter-hint">Filters</Button>
  </PopoverTrigger>
  <PopoverContent>
    <span id="filter-hint" className="sr-only">
      Opens a panel to configure search filters
    </span>
    {/* Filter form content */}
  </PopoverContent>
</Popover>