Popover

When to UseCopy Anchor Link

• for one or two fields that change a setting in place, such as the days before a payment reminder
• to explain one item on the page, like why a message was not delivered
• to show a Calendar for choosing a date

When Not to UseCopy Anchor Link

• to name an icon-only Button (use a Tooltip)
• to preview the page behind a link (use a Hover Card)
• to offer a list of actions (use a Dropdown Menu)
• for a task that users have to finish or cancel before anything else (use a Dialog)

AnatomyCopy Anchor Link

* The title is the popup’s accessible name. If the popup has no title, set an aria-label on it.

PopoverContent renders the portal, the positioner, and the popup, so you don’t need to add them.

BehaviorCopy Anchor Link

A Popover isn’t modal: while it is open, the page scrolls and stays interactive, and users can move focus out of the popup with Tab.

By default, the popup opens below the trigger and is centered on it. If the popup doesn’t fit there, Base UI moves it to another side. To change its position, use side, sideOffset, align, and alignOffset on PopoverContent.

The popup is 288px wide and as tall as its content.

AccessibilityCopy Anchor Link

Base UI’s Popover sets the role, moves focus into the popup, and closes when users press Escape. You provide the title that names the popup.

InstallationCopy Anchor Link

npx shadcn@latest add @summit/popover

UsageCopy Anchor Link

import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import {
    Popover,
    PopoverContent,
    PopoverDescription,
    PopoverHeader,
    PopoverTitle,
    PopoverTrigger,
} from '@/components/ui/popover';

<Popover>
    <PopoverTrigger render={<Button variant="outline" />}>Set reminder</PopoverTrigger>
    <PopoverContent>
        <PopoverHeader>
            <PopoverTitle>Payment reminder</PopoverTitle>
            <PopoverDescription>Sent to the client before an invoice is due.</PopoverDescription>
        </PopoverHeader>
        <div className="grid gap-2">
            <Label htmlFor="days">Days before the due date</Label>
            <Input id="days" type="number" defaultValue={3} />
        </div>
    </PopoverContent>
</Popover>;

Open on HoverCopy Anchor Link

If openOnHover is set on PopoverTrigger, the Popover also opens when the pointer has rested on the trigger for 300ms. Touch users and screen reader users can still reach the text, which a Tooltip hides from both. Use openOnHover for the text behind an info icon.

import { InfoIcon } from '@phosphor-icons/react';

<Popover>
    <PopoverTrigger openOnHover render={<Button variant="ghost" size="icon" aria-label="About the tax number" />}>
        <InfoIcon />
    </PopoverTrigger>
    <PopoverContent aria-label="About the tax number">Printed on every invoice you send.</PopoverContent>
</Popover>;

API ReferenceCopy Anchor Link

The parts accept the props of their matching parts in Base UI’s Popover, where PopoverContent is Popover.Popup. PopoverHeader accepts the props of a div. Summit doesn’t wrap the close button, the arrow, or the backdrop of Base UI’s Popover. See the Base UI Popover documentation for modal, openOnHover, initialFocus, finalFocus, and Popover.Close.

PopoverContentCopy Anchor Link