Is the ai2 Popover compatible with shadcn/ui?

Yes. It uses the same anatomy (Popover, PopoverTrigger, PopoverContent, PopoverAnchor) and installs through the standard shadcn registry format, so it drops into any shadcn/ui project and existing snippets keep working.

Is the popover accessible?

Yes. It is built on the radix-ui Popover primitive: the trigger reports state through aria-expanded, Escape and outside clicks dismiss the panel, and focus returns to the trigger when it closes.

How do I install the ai2 Popover?

Run npx shadcn add @ai2/popover with the ai2 registry configured in components.json. An MCP agent can run the same install for you, or you can copy the source from this page manually.

Can an AI agent install and use this component?

Yes. The registry item ships agent-readable metadata and a working example, and the page provides a copy prompt. Point the shadcn MCP server at the @ai2 registry and the agent can search, inspect and install it on its own.

How do I control which side the popover opens on?

Pass side (top, right, bottom, left) and align (start, center, end) to PopoverContent. They forward straight to radix, which flips the panel automatically when the preferred side would leave the viewport.

Does it work inside overflow-hidden or scrollable containers?

Yes. The content renders in a portal at the document root, so clipping and stacking contexts on ancestors do not affect it. The panel keeps tracking its trigger position.

Can I anchor the panel to an element other than the trigger?

Yes. Render PopoverAnchor around the reference element and radix positions the panel against it instead of the trigger. This is useful for toolbars and inputs with attached panels.

When should I use Popover instead of DropdownMenu or Tooltip?

Use Popover for rich interactive content such as forms, filters and pickers. DropdownMenu is for a list of actions with menu semantics, and Tooltip is for short text shown on hover or focus only.

Does it work in controlled mode?

Yes. Pass open and onOpenChange to the Popover root to drive it from React state, or leave it uncontrolled and let the trigger manage open and close.

Popover

A floating panel anchored to a trigger, rendered in a portal so it escapes overflow-hidden parents, with directional slide/zoom animations.

overlay

A free styled version is available

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

export default function PopoverDemo() {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="outline">Open popover</Button>
      </PopoverTrigger>
      <PopoverContent size="sm">
        <p className="text-sm font-medium">Region status</p>
        <p className="text-sm text-muted-foreground">All 3 regions healthy.</p>
      </PopoverContent>
    </Popover>
  )
}

Installation

Run the following command

npx shadcn@latest add @ai2/popover

Dependencies, the @ai2/tokens theme and the component file are installed together.

Install dependencies

npm install radix-ui@^1.6.1 tw-animate-css@^1.4.0

Add the cn util

lib/utils.ts

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

/* Adds a source-attribution ref param to a URL (the inspiration exports mark their
   outbound links with an ai2.design attribution). An invalid URL is returned as is.

   This file is SHOWN TO THE CONSUMER: the docs component pages render the source of
   `cn` in a code block, so a Turkish comment here would reach every one of those
   pages. Keep it English. */
export function withRef(url: string, ref = "ai2.design"): string {
  try {
    const u = new URL(url)
    u.searchParams.set("ref", ref)
    return u.toString()
  } catch {
    return url
  }
}

Copy the source code

components/ui/popover.tsx

"use client"

import type * as React from "react"
import { Popover as PopoverPrimitive } from "@/components/ui/primitives"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

const popoverContentVariants = cva(
  "z-50 max-w-[calc(100vw-2rem)] origin-(--radix-popover-content-transform-origin) rounded-lg border border-border bg-popover p-4 text-popover-foreground shadow-md outline-none data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-1 data-[side=left]:slide-in-from-right-1 data-[side=right]:slide-in-from-left-1 data-[side=top]:slide-in-from-bottom-1 motion-reduce:animate-none",
  {
    variants: {
      size: {
        sm: "w-56",
        md: "w-72",
        lg: "w-80",
      },
    },
    defaultVariants: { size: "md" },
  }
)

function Popover(props: React.ComponentProps<typeof PopoverPrimitive.Root>) {
  return <PopoverPrimitive.Root data-slot="popover" {...props} />
}

function PopoverTrigger(props: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
}

function PopoverAnchor(props: React.ComponentProps<typeof PopoverPrimitive.Anchor>) {
  return <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />
}

function PopoverContent({
  className,
  align = "center",
  sideOffset = 6,
  size,
  ...props
}: React.ComponentProps<typeof PopoverPrimitive.Content> &
  VariantProps<typeof popoverContentVariants>) {
  return (
    <PopoverPrimitive.Portal>
      <PopoverPrimitive.Content
        data-slot="popover-content"
        data-size={size ?? "md"}
        align={align}
        sideOffset={sideOffset}
        className={cn(popoverContentVariants({ size, className }))}
        {...props}
      />
    </PopoverPrimitive.Portal>
  )
}

export {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverAnchor,
  popoverContentVariants,
}

Manual installs skip the @ai2/tokens theme - add the token CSS from the theming guide or the tone colors will be missing.

Usage

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

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Open popover</Button>
  </PopoverTrigger>
  <PopoverContent>
    <p className="text-sm font-medium">Region status</p>
    <p className="text-sm text-muted-foreground">All 3 regions healthy.</p>
  </PopoverContent>
</Popover>

The content renders in a portal, so it escapes overflow-hidden parents. Use PopoverAnchor to position the panel against an element other than the trigger.

Examples

Alignment

Sizes

Custom width and offset

Props

PopoverContent sets these defaults; every part also forwards its underlying radix props - e.g. open / onOpenChange on Popover and side on PopoverContent.

Prop	Type	Default	Description
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Panel width preset: sm is w-56, md is w-72, lg is w-80.
`align`	`"start" \| "center" \| "end"`	`"center"`	Alignment of the panel relative to the trigger.
`sideOffset`	`number`	`6`	Gap in pixels between the trigger and the panel.

ai2 Popover: an anchored floating panel for React

The ai2 Popover is a shadcn-compatible popover component for React, built on the radix-ui Popover primitive and styled with Tailwind CSS v4. It anchors a floating panel to a trigger, renders it in a portal so it escapes overflow-hidden parents and stacking contexts, and animates open and close with a directional fade, zoom and slide that always matches the side the panel opens from.

Because it ships through the shadcn registry format, you install it with one CLI command, an MCP agent, or a copy-paste, and the source lands in your own project. You own the file; there is no runtime dependency on ai2 itself. The live example above is the exact component you get.

What is the ai2 Popover?

It is a four-part composition: Popover, PopoverTrigger, PopoverContent and PopoverAnchor. The anatomy matches shadcn/ui exactly, so existing snippets, muscle memory and AI agents keep working without changes.

The content defaults to a 288px panel centered on the trigger with a 6px gap, and every radix Content prop is forwarded, so side, align, sideOffset and the collision options are one prop away. When the trigger is not the right reference point, PopoverAnchor positions the panel against any other element.

Why use it

Anchored positioning with collision handling: The radix-ui positioning engine keeps the panel attached to its trigger and flips it to the opposite side when it would leave the viewport, with no positioning code on your side.
Portal rendering: The panel renders in a portal at the document root, so it escapes overflow-hidden parents, table cells and transformed ancestors that break absolutely positioned menus.
Focus and dismiss behavior: Escape and outside clicks close the panel, focus returns to the trigger on close, and the trigger reports its state through aria-expanded. All of it comes from the radix primitive.
Direction-aware motion: The panel fades, zooms and slides in from the side it opens on, driven by data-state and data-side attributes, so the animation always matches the actual placement.
Agent-readable metadata: The registry item describes its parts and intended use in plain words, so an MCP agent can find, inspect and install it without guessing.

Features

shadcn registry install: One command adds the component, its dependencies and the @ai2/tokens theme to your project.
PopoverAnchor part: Anchor the panel to an element other than the trigger, useful for toolbars, text selections and input adornments.
Sensible defaults, full override: align defaults to center, sideOffset to 6 and size to md (w-72); all are plain props, and a size of sm (w-56) or lg (w-80) swaps the width without touching className.
Anchor-based transform origin: The zoom animation originates from the radix transform-origin variable, so the panel grows out of the trigger instead of scaling from its own center.
Data attributes for styling: The panel exposes data-slot, data-state and data-side, so you can restyle open, closed and per-side appearance from CSS without forking the component.
TypeScript source: The file you install is typed end to end and forwards every radix prop, so autocomplete covers the full API including open, onOpenChange, side and modal.

Production tips

Use asChild on the trigger: Wrap an ai2 Button with PopoverTrigger asChild so the trigger keeps button styling and semantics instead of nesting two interactive elements.
Size the panel for its content: The size prop steps the width in three presets (sm w-56, md w-72, lg w-80). For anything outside that scale, override with className, and prefer a max-height with scrolling over a panel taller than the viewport.
Adjust spacing with sideOffset: Change the trigger-to-panel gap with sideOffset instead of margins; margins on the content interfere with the positioning engine.
Pick the right overlay: Use Popover for rich interactive content, DropdownMenu for a list of actions, and Tooltip for short hover-only hints. Screen reader behavior differs between the three.
Test near viewport edges: Collision handling flips the panel and updates data-side. If you add custom per-side styling, open the popover at the bottom and edges of the screen to verify both placements.

Works with the rest of ai2

The popover composes naturally with the rest of the registry. Wrap an ai2 Button as the trigger, build compact settings panels with ai2 Field rows inside the content, or combine it with ai2 Command to build searchable pickers.

For neighboring patterns, the ai2 Combobox is exactly this popover plus command list wired together, and ai2 Tooltip covers the hover-only cases where a popover would be too heavy. Everything shares one token source, so combinations stay visually consistent in both modes.