popover

Displays rich content in a floating layer, triggered by an anchor element.

About

Popover built with @floating-ui/react and Popper-based primitives for collision-aware positioning.

Philosophy

Popovers bridge the gap between tooltips (hover, no interaction) and dialogs (heavy, blocking). They're the right choice for inline forms, color pickers, and contextual actions that need more space than a tooltip but shouldn't interrupt the user's flow. We handle positioning and collision detection so you can focus on content.

How It's Built

Loading diagram...

Installation

npx @gentleduck/cli add popover

npx @gentleduck/cli add popover

Usage

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

<Popover>
  <PopoverTrigger>Open</PopoverTrigger>
  <PopoverContent>Place content for the popover here.</PopoverContent>
</Popover>

Examples

Sides

Form

Active Trigger on Open

Style the trigger to appear active while the popover is open using data-[state=open]:

Arrow

Add a directional caret pointing at the trigger. The arrow tracks the trigger and slides along the content edge during collision avoidance. Use arrowPadding to keep it within the rounded corners.

Customize the border color via --popover-border-color on PopoverContent:

<PopoverContent style={{ '--popover-border-color': '#5865f2' }}>
  ...
  <PopoverArrow />
</PopoverContent>

Component Composition

Loading diagram...

RTL Support

Set the direction once with DirectionProvider (or <html dir="rtl">) and the popover follows. The portaled content gets the resolved dir, and side="left"/side="right" and align="start"/align="end" mirror with it.

<DirectionProvider dir="rtl">
  <Popover>
    <PopoverTrigger>فتح</PopoverTrigger>
    <PopoverContent>محتوى النافذة المنبثقة هنا.</PopoverContent>
  </Popover>
</DirectionProvider>

Motion

Alpha: Motion Compositions

Motion components work standalone, but some compositions may behave unexpectedly: this is still under active development. If you find a broken composition, please file an issue.

Use MotionPopover and MotionPopoverContent for smooth enter/exit animations powered by motion. The transform origin matches the placement side automatically.

Requires the motion package. Use MotionPopover instead of Popover and MotionPopoverContent instead of PopoverContent. All other sub-components (PopoverTrigger, PopoverClose, etc.) stay the same.

API Reference

Prop	Type	Default	Description
`children`	`React.ReactNode`	`-`	Popover sub-components (`PopoverTrigger`, `PopoverContent`)
`defaultOpen`	`boolean`	`-`	Initial open state for uncontrolled usage
`open`	`boolean`	`-`	Controlled open state
`onOpenChange`	`(open: boolean) => void`	`-`	Callback when open state changes
`modal`	`boolean`	`false`	Enables modal focus/interaction behavior
`dir`	`'ltr' \| 'rtl'`	-	Optional override. Resolved by primitives `useDirection` (`dir` prop -> `DirectionProvider` -> `<html dir>`).
`...props`	`React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Root>`	-	Additional props inherited from `Popover.Root`.

PopoverTrigger

Prop	Type	Default	Description
`asChild`	`boolean`	`--`	Use the child element as the trigger
`...props`	`React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Trigger>`	-	Additional props inherited from `Popover.Trigger`.

PopoverContent

Prop	Type	Default	Description
`forceMount`	`boolean`	`-`	Keep content mounted for animation control
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'bottom'`	Preferred side relative to the trigger
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Alignment on the chosen side
`sideOffset`	`number`	`4`	Main-axis offset from trigger
`alignOffset`	`number`	`0`	Cross-axis offset from trigger
`...props`	`React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>`	-	Additional props inherited from `Popover.Content`.

PopoverClose

Element that closes the popover when interacted with.

Prop	Type	Default	Description
`asChild`	`boolean`	`false`	Renders child as the close control
`children`	`React.ReactNode`	-	Close control content
`...props`	`React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Close>`	-	Additional props inherited from `PopoverPrimitive.Close`

PopoverAnchor

Optional custom anchor element for positioning.

Prop	Type	Default	Description
`...props`	`React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Anchor>`	-	Additional props inherited from `Popover.Anchor`.

MotionPopover

Wraps with useMotionRoot for exit animation support. Requires the motion package.

Prop	Type	Default	Description
`...props`	`PopoverProps`	-	All props from `Popover` are supported

MotionPopoverContent

Adds a scaleIn enter/exit animation (fade, scale, and blur) with a springBouncy transition, like the other motion popups. Requires the motion package.

Prop	Type	Default	Description
`...props`	`PopoverContentProps`	-	All props from `PopoverContent` are supported