Popover

Once per app, add the registry to components.json:

{
  "registries": {
    "@pixilui": "https://pixilui.com/r/{name}.json"
  }
}

Or install from the URL, no namespace needed: npx shadcn@latest add https://pixilui.com/r/popover.json

1. 1

   Install the npm packages.

   TerminalCopy

   npm install @base-ui/react motion clsx tailwind-merge

2. 2

   Add the items it depends on, the same way.

   • Foundation
   • Button
3. 3

   Copy each file to the path shown.

   components/pixilui/popover.tsxCopy

   "use client";
   
   import {
     forwardRef,
     isValidElement,
     useCallback,
     useId,
     useState,
     type ComponentPropsWithoutRef,
     type ReactElement,
     type ReactNode,
   } from "react";
   import { Popover as BasePopover } from "@base-ui/react/popover";
   import { AnimatePresence, motion, useReducedMotion } from "motion/react";
   import { cn } from "./lib/utils";
   import { motionTokens, reducedTransition } from "./motion-tokens";
   import { Button, type ButtonProps } from "./button";
   
   export type PopoverSide = "top" | "bottom" | "left" | "right";
   export type PopoverAlign = "start" | "center" | "end";
   
   export type PopoverProps = Omit<ComponentPropsWithoutRef<"div">, "children"> & {
     /** What the panel holds: PopoverTitle, PopoverDescription, controls, PopoverClose. */
     children?: ReactNode;
     /** The element the panel anchors to and opens from, usually a Button. Rendered through Base UI's render prop. */
     trigger: ReactElement;
     /** Controlled open state. Pair with onOpenChange. */
     open?: boolean;
     /** Starting open state when uncontrolled. */
     defaultOpen?: boolean;
     /** Runs whenever the popover opens or closes. */
     onOpenChange?: (open: boolean) => void;
     /** Preferred side of the trigger. It flips when there is no room. */
     side?: PopoverSide;
     /** Alignment along that side. */
     align?: PopoverAlign;
     /** Gap between the trigger and the panel, in px. */
     offset?: number;
     /** Draw a small arrow pointing at the trigger. */
     arrow?: boolean;
     /** Also open when the trigger is hovered (fine pointers only). Clicks still toggle it. */
     hoverOpen?: boolean;
     /** Where the popover portals to. Defaults to document.body. Pass an element (from a callback ref kept in state) to keep it inside a region; null waits for it. */
     container?: HTMLElement | null;
   };
   
   /** Keeps the arrow clear of the panel's rounded corners. */
   const ARROW_PADDING = 22;
   
   function PopoverArrow() {
     return (
       <BasePopover.Arrow
         data-slot="popover-arrow"
         className={cn(
           "flex",
           "data-[side=bottom]:-top-2 data-[side=top]:-bottom-2 data-[side=top]:rotate-180",
           "data-[side=left]:-right-3 data-[side=left]:rotate-90 data-[side=right]:-left-3 data-[side=right]:-rotate-90",
         )}
       >
         <svg width="20" height="10" viewBox="0 0 20 10" aria-hidden="true">
           <path d="M0 10C4 10 6.5 2 10 2s6 8 10 8" className="fill-surface-raised" />
           <path d="M0 10C4 10 6.5 2 10 2s6 8 10 8" fill="none" className="stroke-border" strokeWidth="1" />
         </svg>
       </BasePopover.Arrow>
     );
   }
   
   export const Popover = forwardRef<HTMLDivElement, PopoverProps>(function Popover(
     {
       children,
       trigger,
       open: openProp,
       defaultOpen = false,
       onOpenChange,
       side = "bottom",
       align = "center",
       offset = 8,
       arrow = false,
       hoverOpen = false,
       container,
       className,
       ...rest
     },
     forwardedRef,
   ) {
     const reduced = useReducedMotion() ?? false;
     const [innerOpen, setInnerOpen] = useState(defaultOpen);
     const open = openProp ?? innerOpen;
     const generatedTriggerId = useId();
     const triggerId = (isValidElement<{ id?: string }>(trigger) && trigger.props.id) || generatedTriggerId;
   
     const setOpen = useCallback(
       (next: boolean) => {
         setInnerOpen(next);
         onOpenChange?.(next);
       },
       [onOpenChange],
     );
   
     const panel = reduced
       ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: reducedTransition }
       : {
           initial: { opacity: 0, scale: motionTokens.scale.enterFrom },
           animate: { opacity: 1, scale: 1 },
           exit: {
             opacity: 0,
             scale: motionTokens.scale.enterFrom,
             transition: { duration: motionTokens.duration.quick, ease: motionTokens.ease.exit },
           },
           transition: {
             scale: motionTokens.spring.snappy,
             opacity: { duration: motionTokens.duration.quick, ease: motionTokens.ease.enter },
           },
         };
   
     const nativeButton = typeof trigger.type === "string" ? trigger.type === "button" : true;
   
     return (
       <BasePopover.Root open={open} triggerId={triggerId} onOpenChange={(next) => setOpen(next)}>
         <BasePopover.Trigger id={triggerId} nativeButton={nativeButton} openOnHover={hoverOpen} render={trigger} />
         <AnimatePresence>
           {open ? (
             <BasePopover.Portal keepMounted container={container}>
               <BasePopover.Positioner side={side} align={align} sideOffset={offset} arrowPadding={ARROW_PADDING} className="z-50 outline-none">
                 <BasePopover.Popup
                   ref={forwardedRef}
                   data-slot="popover"
                   data-state={open ? "open" : "closed"}
                   className={cn(
                     "w-max max-w-[min(var(--available-width),22rem)] origin-(--transform-origin) rounded-panel bg-surface-raised p-4 font-body text-14 text-foreground shadow-floating outline-none hairline",
                     className,
                   )}
                   render={<motion.div {...panel} />}
                   {...rest}
                 >
                   {arrow ? <PopoverArrow /> : null}
                   {children}
                 </BasePopover.Popup>
               </BasePopover.Positioner>
             </BasePopover.Portal>
           ) : null}
         </AnimatePresence>
       </BasePopover.Root>
     );
   });
   
   export type PopoverTitleProps = ComponentPropsWithoutRef<"h2">;
   
   /** Names the popover; Base UI wires it to aria-labelledby. */
   export const PopoverTitle = forwardRef<HTMLHeadingElement, PopoverTitleProps>(function PopoverTitle({ className, ...rest }, ref) {
     return <BasePopover.Title ref={ref} className={cn("text-14 font-medium text-foreground", className)} {...rest} />;
   });
   
   export type PopoverDescriptionProps = ComponentPropsWithoutRef<"p">;
   
   /** Supporting sentence; Base UI wires it to aria-describedby. */
   export const PopoverDescription = forwardRef<HTMLParagraphElement, PopoverDescriptionProps>(function PopoverDescription({ className, ...rest }, ref) {
     return <BasePopover.Description ref={ref} className={cn("mt-1 text-pretty text-14 text-secondary", className)} {...rest} />;
   });
   
   export type PopoverCloseProps = ButtonProps;
   
   /** A Button that closes the popover and returns focus to the trigger. Secondary and small by default. */
   export const PopoverClose = forwardRef<HTMLButtonElement, PopoverCloseProps>(function PopoverClose(
     { variant = "secondary", size = "sm", icon, iconEnd, loading, ...rest },
     ref,
   ) {
     return (
       <BasePopover.Close
         ref={ref}
         render={(props) => <Button {...(props as ButtonProps)} variant={variant} size={size} icon={icon} iconEnd={iconEnd} loading={loading} />}
         {...(rest as ComponentPropsWithoutRef<"button">)}
       />
     );
   });

4. 4

   Check that your global stylesheet imports the foundation, after Tailwind.

   app/globals.cssCopy

   @import "tailwindcss";
   @import "../components/pixilui/foundation.css";