Tooltip

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/tooltip.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
3. 3

   Copy each file to the path shown.

   components/pixilui/tooltip.tsxCopy

   "use client";
   
   import {
     cloneElement,
     createContext,
     forwardRef,
     useCallback,
     useContext,
     useId,
     useState,
     useSyncExternalStore,
     type ComponentPropsWithoutRef,
     type ReactElement,
     type ReactNode,
   } from "react";
   import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
   import { AnimatePresence, motion, useReducedMotion, type HTMLMotionProps } from "motion/react";
   import { cn } from "./lib/utils";
   import { instantTransition, motionTokens, reducedTransition } from "./motion-tokens";
   
   export type TooltipSide = "top" | "bottom" | "left" | "right";
   export type TooltipAlign = "start" | "center" | "end";
   
   export type TooltipProps = Omit<ComponentPropsWithoutRef<"div">, "children"> & {
     /** The element the tooltip describes, usually an icon Button. Give it its own aria-label; the tooltip is a visual label. */
     children: ReactElement<{ "aria-describedby"?: string; "aria-label"?: string }>;
     /** The text. Plain text by design: a tooltip never holds links or buttons. */
     label: string;
     /** A keyboard shortcut shown after the label in mono, such as "⌘K". */
     shortcut?: string;
     /** Preferred side of the trigger. It flips when there is no room. */
     side?: TooltipSide;
     /** Alignment along that side. */
     align?: TooltipAlign;
     /** Gap between the trigger and the tooltip, in px. */
     offset?: number;
     /** Controlled open state, for tours and tests. Pair with onOpenChange. */
     open?: boolean;
     /** Starting open state when uncontrolled. */
     defaultOpen?: boolean;
     /** Runs whenever the tooltip opens or closes. */
     onOpenChange?: (open: boolean) => void;
     /** Where the tooltip 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;
   };
   
   /** Hover this long before a tooltip opens. */
   const OPEN_DELAY = 400;
   /** A neighbour opened within this long of the last close opens at once. */
   const GROUP_TIMEOUT = 300;
   
   const TooltipGroupContext = createContext(false);
   
   export type TooltipProviderProps = {
     /** The tooltips that share the instant re-open, such as one toolbar. */
     children?: ReactNode;
   };
   
   /**
    * Groups tooltips: after one closes, moving to a neighbour within 300ms opens it at once
    * instead of waiting 400ms again. A lone Tooltip groups itself.
    */
   export function TooltipProvider({ children }: TooltipProviderProps) {
     return (
       <BaseTooltip.Provider delay={OPEN_DELAY} timeout={GROUP_TIMEOUT}>
         <TooltipGroupContext.Provider value>{children}</TooltipGroupContext.Provider>
       </BaseTooltip.Provider>
     );
   }
   
   const coarseQuery = "(pointer: coarse)";
   const subscribeCoarse = (onChange: () => void) => {
     const list = window.matchMedia(coarseQuery);
     list.addEventListener("change", onChange);
     return () => list.removeEventListener("change", onChange);
   };
   const readCoarse = () => window.matchMedia(coarseQuery).matches;
   const readCoarseOnServer = () => false;
   
   export const Tooltip = forwardRef<HTMLDivElement, TooltipProps>(function Tooltip(
     {
       children,
       label,
       shortcut,
       side = "top",
       align = "center",
       offset = 6,
       open: openProp,
       defaultOpen = false,
       onOpenChange,
       container,
       className,
       ...rest
     },
     forwardedRef,
   ) {
     const reduced = useReducedMotion() ?? false;
     const coarse = useSyncExternalStore(subscribeCoarse, readCoarse, readCoarseOnServer);
     const grouped = useContext(TooltipGroupContext);
     const [innerOpen, setInnerOpen] = useState(defaultOpen);
     const open = (openProp ?? innerOpen) && !coarse;
     const descriptionId = useId();
   
     const setOpen = useCallback(
       (next: boolean) => {
         setInnerOpen(next);
         onOpenChange?.(next);
       },
       [onOpenChange],
     );
   
     // Base UI leaves tooltips out of the accessibility tree, so the text is also wired to the
     // trigger as a description, unless it would only repeat the trigger's own name.
     const text = shortcut ? `${label} (${shortcut})` : label;
     const ownName = children.props["aria-label"];
     const describe = ownName !== label && ownName !== text;
     const describedBy = describe ? [children.props["aria-describedby"], descriptionId].filter(Boolean).join(" ") : children.props["aria-describedby"];
     const description = describe ? (
       <span id={descriptionId} hidden>
         {text}
       </span>
     ) : null;
   
     // Touch screens never hover, so render the trigger alone. The description stays for screen readers.
     if (coarse) {
       return (
         <>
           {cloneElement(children, { "aria-describedby": describedBy })}
           {description}
         </>
       );
     }
   
     const enter = reduced
       ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 } }
       : {
           initial: { opacity: 0, scale: motionTokens.scale.enterFrom },
           animate: { opacity: 1, scale: 1 },
           exit: { opacity: 0, transition: { duration: motionTokens.duration.instant, ease: motionTokens.ease.exit } },
         };
   
     const tooltip = (
       <BaseTooltip.Root open={open} onOpenChange={(next) => setOpen(next)}>
         <BaseTooltip.Trigger render={children} aria-describedby={describedBy} />
         <AnimatePresence>
           {open ? (
             <BaseTooltip.Portal keepMounted container={container}>
               <BaseTooltip.Positioner side={side} align={align} sideOffset={offset} className="z-50">
                 <BaseTooltip.Popup
                   ref={forwardedRef}
                   data-slot="tooltip"
                   data-state={open ? "open" : "closed"}
                   className={cn(
                     "flex max-w-64 origin-(--transform-origin) items-baseline gap-2 rounded-control bg-surface-inverted px-2.5 py-1.5 font-body text-12 font-medium text-inverted shadow-raised",
                     className,
                   )}
                   render={(props, state) => (
                     <motion.div
                       {...(props as HTMLMotionProps<"div">)}
                       {...enter}
                       // A grouped re-open is instant, like the first tooltip never closed.
                       transition={
                         state.instant
                           ? instantTransition
                           : reduced
                             ? reducedTransition
                             : { duration: motionTokens.duration.quick, ease: motionTokens.ease.enter }
                       }
                     />
                   )}
                   {...rest}
                 >
                   <span className="min-w-0 text-pretty">{label}</span>
                   {shortcut ? (
                     <kbd data-slot="tooltip-shortcut" className="shrink-0 font-mono text-12 font-normal text-inverted/60">
                       {shortcut}
                     </kbd>
                   ) : null}
                 </BaseTooltip.Popup>
               </BaseTooltip.Positioner>
             </BaseTooltip.Portal>
           ) : null}
         </AnimatePresence>
       </BaseTooltip.Root>
     );
   
     return (
       <>
         {grouped ? tooltip : <TooltipProvider>{tooltip}</TooltipProvider>}
         {description}
       </>
     );
   });

4. 4

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

   app/globals.cssCopy

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