Popover

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add popover

Usage#

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
} from "@/components/ui/popover"

export function Example() {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="outline">Open</Button>
      </PopoverTrigger>
      <PopoverContent>Content</PopoverContent>
    </Popover>
  )
}

Anatomy#

import {
  Popover,
  PopoverTrigger,
  PopoverAnchor,
  PopoverContent,
  PopoverViewport,
  PopoverCloseButton,
  PopoverMedia,
  PopoverTitle,
  PopoverDescription,
  PopoverClose,
  PopoverFooter,
} from "@/components/ui/popover"

<Popover>
  <PopoverTrigger />
  <PopoverAnchor />
  <PopoverContent>
    <PopoverCloseButton />
    <PopoverMedia />
    <PopoverTitle />
    <PopoverDescription />
    <PopoverClose />
    <PopoverFooter />
  </PopoverContent>
</Popover>

// One popover, many triggers
<Popover>
  <PopoverTrigger payload={a} />
  <PopoverTrigger payload={b} />
  <PopoverContent>
    <PopoverViewport>{(payload) => …}</PopoverViewport>
  </PopoverContent>
</Popover>

With a form#

The canonical use case. Because the content exposes --surface, nested Inputs paint the panel surface rather than the page. Wrap actions in PopoverClose to dismiss on click.

With arrow & close button#

Set showArrow for a pointer toward the trigger, and use PopoverCloseButton for a styled top-right dismiss.

Alignment#

Control placement along the trigger with align (start · center · end) and side / sideOffset, all forwarded to Radix.

Density#

density tunes the content padding: compact for dense application UI. It also cascades from a surrounding DensityProvider.

Open on hover#

Set openOnHover on the trigger (or the root, for every trigger). It opens after delay and stays open while the pointer crosses into the panel and rests in it. A click pins it open, and touch and keyboard keep the click behaviour.

Hovering a link to peek at where it goes is a HoverCard: it never takes focus and never opens on touch, so it only previews. A hover Popover is still a dialog. Its trigger is a button, a click or Enter opens it, and it can hold a form.

Multiple triggers#

Any number of triggers can open one popover. Give each a payload and pass the content a function of it. One panel serves the whole table, and only the active row's trigger reads as expanded.

Detached triggers#

Triggers can live outside the Popover, in another component. Create a handle once with createPopoverHandle() and pass it to the root and to each trigger. The handle also opens and closes the popover from code.

To control it, pass open and triggerId, and read the new trigger from onOpenChange, which also fires on a switch.

const [open, setOpen] = useState(false)
const [triggerId, setTriggerId] = useState<string | null>(null)

<Popover
  open={open}
  triggerId={triggerId}
  onOpenChange={(next, { triggerId }) => {
    setOpen(next)
    setTriggerId(triggerId)
  }}
>
  …
</Popover>

Animating between triggers#

Moving from one trigger to another never closes the panel. It glides to the new trigger, eases to the new size, and the contents slide in the direction it moved. The first open lands in place. Each payload sets its own width, here w-64 on the card.

A function child renders inside a PopoverViewport. Place one yourself to style the switch. Hide the leaving contents for a plain resize, or key off data-activation-direction, data-current and data-previous.

<PopoverContent>
  <PopoverViewport className="[&>[data-previous]]:hidden">
    {(member: Member) => <MemberCard member={member} />}
  </PopoverViewport>
</PopoverContent>

Confirm an action#

A lightweight inline confirm for a destructive action. The footer pairs a ghost Cancel with a destructive primary, each wrapped in PopoverClose so either choice dismisses.

Profile card#

A richer surface: compose an Avatar with identity and actions for a hover-card style preview.

Media and footer#

PopoverMedia frames a picture or video 8px in from the panel's edges, first or last, with corners concentric to the panel's (16px outside, 8px on the picture). PopoverFooter closes the panel with a muted well on the same inset, where a divider line would otherwise go; its text lands back on the copy's line. At compact both sit 4px in, with 12px corners.

Share a link#

A read-only Input blends with the panel through --surface, and the copy button swaps to a confirmation for a beat after a click.

Feedback prompt#

A common composition: pair the surface with a ToggleGroup for a "Was this useful?" rating. The control is its own label, so no inputs are needed. Shown here always visible as a card; the same content drops straight into a PopoverContent.

A compact take drops the subtitle and swaps in a thank-you once answered.

And floated in the popover itself, revealed from a trigger.

API reference#

FAQ#