Are the ai2 Placement popovers free?

Yes. The whole styled layer is free and MIT licensed, like the component core.

Can I change the size?

Yes. Every variation takes a size prop of sm, md, lg or xl, aligned to the base Button height scale.

Placement popovers

Five popovers that anchor in different directions relative to the trigger: top, bottom, left, right and corner. Each is self-contained (no radix), sized, token-driven, opens on click and closes on outside click or Escape, and slides in from its own direction.

PopoverPlacement

Installation

The styled layer is free and installs like any other ai2 component.

Run the following command

npx shadcn@latest add @ai2/popover-placement

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

Install dependencies

npm install motion lucide-react

Copy the source

components/ui/popover-placement.tsx

"use client"

import * as React from "react"
import { ArrowDown, ArrowLeft, ArrowRight, ArrowUp, Move } from "lucide-react"
import { AnimatePresence, motion, useReducedMotion } from "motion/react"

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

/* Popover placement family: 5 direction-focused anchored panels. The same mechanism
   as the essentials popover (a relative inline-flex wrapper + the trigger toggling
   on CLICK, closing on an outside click + Escape, NO radix or portal, data-slot
   preserved) but the panel is positioned in DIFFERENT DIRECTIONS relative to the
   trigger: top, bottom, left, right and corner. Each panel enters with a slight
   slide from that direction (motion x/y). In the horizontal placements the vertical
   centering is done with my-auto rather than a transform; that way the centering
   survives even when only a fade remains under reduced motion. Color comes ONLY
   from tokens, via alpha color-mix. */

export type StyledSize = "sm" | "md" | "lg" | "xl"

const panelSize: Record<StyledSize, string> = {
  sm: "w-56",
  md: "w-64",
  lg: "w-72",
  xl: "w-80",
}

interface PopoverProps {
  size?: StyledSize
  trigger?: React.ReactNode
  children?: React.ReactNode
  className?: string
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (o: boolean) => void
}

const panelBase =
  "absolute z-50 rounded-xl border border-border bg-popover p-4 text-sm text-popover-foreground shadow-lg outline-none"

const triggerBtn =
  "inline-flex h-9 shrink-0 select-none items-center justify-center gap-2 whitespace-nowrap rounded-lg border border-border bg-secondary px-4 text-sm font-medium text-secondary-foreground outline-none transition-colors hover:bg-[color-mix(in_oklab,var(--color-foreground)_6%,transparent)] focus-visible:ring-[3px] focus-visible:ring-ring/50 [&_svg]:size-4 [&_svg]:shrink-0 [&_i]:text-base [&_i]:leading-none"

/* Controlled/uncontrolled acik durum yonetimi. */
function usePopoverState(props: PopoverProps) {
  const { open, defaultOpen, onOpenChange } = props
  const isControlled = open !== undefined
  const [internal, setInternal] = React.useState(defaultOpen ?? false)
  const isOpen = isControlled ? open : internal

  const setOpen = React.useCallback(
    (next: boolean) => {
      if (!isControlled) setInternal(next)
      onOpenChange?.(next)
    },
    [isControlled, onOpenChange]
  )

  return { isOpen, setOpen }
}

interface PanelMotion {
  initial: Record<string, number | string>
  animate: Record<string, number | string>
  exit: Record<string, number | string>
  transition?: Record<string, unknown>
}

/* Shared shell: a relative wrapper plus trigger plus an AnimatePresence panel. panelClassName carries the placement direction (position plus origin), panelMotion the entry and exit from that direction. */
function PopoverShell({
  props,
  panelClassName,
  panelMotion,
  children,
}: {
  props: PopoverProps
  panelClassName?: string
  panelMotion: PanelMotion
  children: React.ReactNode
}) {
  const { size = "md", trigger, className } = props
  const { isOpen, setOpen } = usePopoverState(props)
  const reduce = useReducedMotion()
  const wrapperRef = React.useRef<HTMLDivElement>(null)

  React.useEffect(() => {
    if (!isOpen) return
    const onKey = (e: KeyboardEvent) => {
      if (e.key === "Escape") setOpen(false)
    }
    const onPointer = (e: PointerEvent) => {
      const node = wrapperRef.current
      if (node && e.target instanceof Node && !node.contains(e.target)) {
        setOpen(false)
      }
    }
    window.addEventListener("keydown", onKey)
    window.addEventListener("pointerdown", onPointer)
    return () => {
      window.removeEventListener("keydown", onKey)
      window.removeEventListener("pointerdown", onPointer)
    }
  }, [isOpen, setOpen])

  const fade = { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 } }
  const motionProps = reduce ? fade : panelMotion

  return (
    <div ref={wrapperRef} data-slot="styled-popover" className="relative inline-flex">
      <span
        data-slot="styled-popover-trigger"
        className="inline-flex"
        onClick={() => setOpen(!isOpen)}
      >
        {trigger ?? (
          <button type="button" aria-haspopup="dialog" aria-expanded={isOpen} className={triggerBtn}>
            Open
          </button>
        )}
      </span>

      <AnimatePresence>
        {isOpen ? (
          <motion.div
            role="dialog"
            className={cn(panelBase, panelSize[size], panelClassName, className)}
            initial={motionProps.initial}
            animate={motionProps.animate}
            exit={motionProps.exit}
            transition={panelMotion.transition ?? { type: "spring", stiffness: 340, damping: 26 }}
          >
            {children}
          </motion.div>
        ) : null}
      </AnimatePresence>
    </div>
  )
}

/* Yon basligi: kucuk lucide oku + etiket, ardindan govde (children). */
function Placement({ icon, label, children }: { icon: React.ReactNode; label: string; children: React.ReactNode }) {
  return (
    <div className="flex flex-col gap-2">
      <div className="flex items-center gap-2 text-xs font-medium text-muted-foreground [&_svg]:size-4 [&_i]:text-base [&_i]:leading-none">
        {icon}
        {label}
      </div>
      <div className="text-popover-foreground">{children ?? "A placement popover anchored to the trigger."}</div>
    </div>
  )
}

/* Top: positioned ABOVE the trigger, entering with an upward slide. */
export function TopPopover(props: PopoverProps) {
  return (
    <PopoverShell
      props={props}
      panelClassName="bottom-full left-0 mb-2 origin-bottom"
      panelMotion={{
        initial: { opacity: 0, y: 6, scale: 0.96 },
        animate: { opacity: 1, y: 0, scale: 1 },
        exit: { opacity: 0, y: 6, scale: 0.96 },
      }}
    >
      <Placement icon={<ArrowUp />} label="Top">
        {props.children}
      </Placement>
    </PopoverShell>
  )
}

/* Bottom: positioned BELOW the trigger, entering with a downward slide. */
export function BottomPopover(props: PopoverProps) {
  return (
    <PopoverShell
      props={props}
      panelClassName="top-full left-0 mt-2 origin-top"
      panelMotion={{
        initial: { opacity: 0, y: -6, scale: 0.96 },
        animate: { opacity: 1, y: 0, scale: 1 },
        exit: { opacity: 0, y: -6, scale: 0.96 },
      }}
    >
      <Placement icon={<ArrowDown />} label="Bottom">
        {props.children}
      </Placement>
    </PopoverShell>
  )
}

/* Left: positioned to the LEFT of the trigger, vertically centred with my-auto (no transform), entering with a right-to-left slide. */
export function LeftPopover(props: PopoverProps) {
  return (
    <PopoverShell
      props={props}
      panelClassName="right-full top-0 bottom-0 my-auto h-fit mr-2 origin-right"
      panelMotion={{
        initial: { opacity: 0, x: 6, scale: 0.96 },
        animate: { opacity: 1, x: 0, scale: 1 },
        exit: { opacity: 0, x: 6, scale: 0.96 },
      }}
    >
      <Placement icon={<ArrowLeft />} label="Left">
        {props.children}
      </Placement>
    </PopoverShell>
  )
}

/* Right: positioned to the RIGHT of the trigger, vertically centred with my-auto (no transform), entering with a left-to-right slide. */
export function RightPopover(props: PopoverProps) {
  return (
    <PopoverShell
      props={props}
      panelClassName="left-full top-0 bottom-0 my-auto h-fit ml-2 origin-left"
      panelMotion={{
        initial: { opacity: 0, x: -6, scale: 0.96 },
        animate: { opacity: 1, x: 0, scale: 1 },
        exit: { opacity: 0, x: -6, scale: 0.96 },
      }}
    >
      <Placement icon={<ArrowRight />} label="Right">
        {props.children}
      </Placement>
    </PopoverShell>
  )
}

/* Corner: corner or diagonal - positioned at the TOP RIGHT of the trigger, entering diagonally from the bottom left. */
export function CornerPopover(props: PopoverProps) {
  return (
    <PopoverShell
      props={props}
      panelClassName="bottom-full left-full mb-2 ml-2 origin-bottom-left"
      panelMotion={{
        initial: { opacity: 0, x: -6, y: 6, scale: 0.96 },
        animate: { opacity: 1, x: 0, y: 0, scale: 1 },
        exit: { opacity: 0, x: -6, y: 6, scale: 0.96 },
      }}
    >
      <Placement icon={<Move />} label="Corner">
        {props.children}
      </Placement>
    </PopoverShell>
  )
}

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

Variations

5 takes on the same idea. Each is its own export, and every one accepts a size prop (sm, md, lg, xl) aligned to the base Button scale.

Top

Anchored above the trigger and slides up into place.

Bottom

Anchored below the trigger and slides down into place.

Left

Anchored to the left, vertically centered, slides in from the right.

Right

Anchored to the right, vertically centered, slides in from the left.

Corner

Anchored to the top-right corner and slides in on the diagonal.

ai2 Placement popovers: 5 styled variations on the token system

The ai2 Placement popovers are a set of 5 decorative button variations from the styled layer of the @ai2 design system, built around click-anchored floating panels placed in a specific direction. They are free and MIT licensed, and every color comes from a semantic token, so they theme with the rest of ai2 in light and dark.

Motion runs on framer-motion: framer-motion slides each panel in from its own direction (up, down, left, right or diagonal) and fades it on exit. The styled layer is opt-in, so the dependency only lands if you use it; the base components stay lean. Under reduced motion, the slide and scale are skipped and the panel fades in place.

What is in the ai2 Placement popovers?

5 exports in one file: Top, Bottom, Left, Right and Corner. Each renders a native button and takes a size prop (sm, md, lg, xl) aligned to the base Button. They are separate from the base Button on purpose: the base keeps its clean variant, tone and size axes, while the styled layer carries the effects.

You own the file. Copy the one category file and you have all 5 variations, with no runtime dependency on ai2 itself.

Why use it

On-system by construction: Every color resolves to an ai2 semantic token, so the buttons follow your theme in light and dark with no extra work.
Effect without the sprawl: The decorations live in a dedicated styled file, so the base Button keeps its clean, predictable API.
Accessible and honest: Each renders a real button element, keeps a visible focus ring, and respects prefers-reduced-motion.

Features

Token-driven color: No hardcoded hex or oklch; the look recolors with your theme tokens.
framer-motion: framer-motion slides each panel in from its own direction (up, down, left, right or diagonal) and fades it on exit.
Reduced-motion aware: Under prefers-reduced-motion, the slide and scale are skipped and the panel fades in place.
Size aligned to the base: Every variation takes sm, md, lg and xl matching the base Button height scale, so styled and base buttons line up in a row.

Production tips

Use it for emphasis, not everywhere: Styled buttons draw the eye. Reserve them for the one action you want people to take on a screen, and use the base Button for the rest.
Keep labels as verbs: The decoration adds weight, so a clear action label keeps the button scannable.
Pick one variation per surface: The variations share a family; using two different ones in the same view competes for attention.

Works with the rest of ai2

The Placement popovers sit alongside the base Button and the rest of the @ai2 registry. They share the same token file, so a styled action next to a base button or a badge stays visually consistent in both modes.