Skip to content

Design system

Documentation

DesignComponents / Popover

Components / Popover

Beta

Popover

Use Popover for anchored context or a short interactive task that should not block the rest of the page.

On this page

Examples

Informational popover

A titled popup gives more context without creating a modal task.

Informational Popover with title, description, arrow, and close

Positions and arrow

Side, alignment, spacing, and an optional arrow keep the popup anchored.

Popover with configurable placement

Small form

Interactive content belongs in a popover when it is brief and related to its trigger.

Popover containing a small form

Long content

A bounded popup scrolls its growing content instead of clipping it.

Popover with bounded long content

Popover inside Dialog

Nested layers keep their focus and portal boundaries explicit.

Popover nested in a Dialog

When to use

Use Popover for a small amount of related content anchored to a trigger. Use Tooltip for passive, brief context and Dialog when the task must take focus or needs confirmation.

Usage

popover-basic.tsx
"use client";

import { Button } from "@phuctech/ui/components/button";
import { Popover, PopoverArrow, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger } from "@phuctech/ui/components/popover";

export function Example() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline">Workspace status</Button>} />
      <PopoverContent>
        <PopoverArrow />
        <PopoverTitle>Workspace status</PopoverTitle>
        <PopoverDescription>All services are operational and the last sync finished a few seconds ago.</PopoverDescription>
        <PopoverClose render={<Button size="sm" variant="ghost">Close</Button>} />
      </PopoverContent>
    </Popover>
  );
}

Give the popup a title when it contains a task, and use PopoverDescription for supporting context. Keep the growing region bounded so long content scrolls inside the popup.

Behavior

  • Click or keyboard activation opens the anchored popup; outside press and Escape close it.
  • Focus returns to the trigger after closing unless the feature supplies an intentional final focus target.
  • side, align, and offset props are preferences; Base UI can flip placement near a viewport edge.

API

Component API
PropTypeDefaultDescriptionConstraints
PopoverRoot propsdefaultOpen=falseOwns open state and modal behavior.Use controlled state only when the feature coordinates visibility.
PopoverTriggertrigger propsButton that anchors and opens the popup.Compose an existing Button through render.
PopoverContentpopup props + side/alignside=bottomPortaled, positioned content surface.Keep content short or provide a bounded scroll region.
PopoverTitle / PopoverDescriptionheading / paragraphAccessible popup name and supporting text.Use a title for interactive tasks.
PopoverCloseclose propsExplicit close action that returns focus.Keep a visible close or cancel action for interactive content.
PopoverArrowarrow propsOptional visual connection to the trigger.The arrow is decorative; do not rely on it for meaning.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-bg-elevated / --elevation-popoverPopup surfacesemantic rolesKeeps the anchored layer distinct from page content.
--radius-xlPopup geometryshared large radiusAligns Popover with Dialog and other elevated surfaces.
--motion-duration-fastOpen/close motion120msKeeps the transient layer responsive.

Accessibility

  • Keep the trigger keyboard reachable and give the popup a title when it is interactive.
  • Verify Escape, outside press, focus return, and nested Dialog behavior.
  • Do not hide a required instruction or error only inside a Popover.
  • Tooltip is the lighter option for brief supplemental context.
  • Dialog handles a focused modal task.
  • Elevation documents portal layering.