ui/hooks/presence

Presence

hookanimationmountunmountpresence

Hook for animating mount/unmount transitions with CSS animations — keeps element in DOM during exit animation, removes after completion.

tsx

1 const ref = useRef<HTMLDivElement>(null);2 const { present } = usePresence({ open, ref });3 4 return present ? (5   <div ref={ref} data-state={open ? "open" : "closed"}>6     {children}7   </div>8 ) : null;

Installation

$pnpm exec dgadd add ui/presence

[Installs to]src/hooks/use-presence.ts[Item]ui/presence

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Parameters

Name	Type	Default	Description
openrequired	boolean	—	Whether the content should be visible. When true, mounts immediately. When false, keeps mounted until the exit animation resolves or the fallback timer fires.
ref	RefObject<HTMLElement \| null>	—	Ref to the animated element. When provided, filters bubbling animationend events from child elements. Recommended when the animated element has children with their own CSS animations.
exitFallbackMs	number	250	Max ms to wait for animationend before forcing the closing -> hidden transition. Raise to at least 2x the exit-animation duration when customizing longer animations.
onExitComplete	() => void	—	Fired after the exit animation resolves, or after exitFallbackMs fires, and the element transitions to hidden.

Returns

{ present: boolean; exiting: boolean; onAnimationEnd: (e: AnimationEvent) => void }Object with present flag for conditional rendering plus optional React-synthetic-event callbacks. When a ref is supplied the hook attaches its own DOM listeners and most consumers only need `present`.

Name	Type	Default	Description
presentrequired	boolean	—	Whether the element should be in the DOM. Use this for conditional rendering.
exitingrequired	boolean	—	True during the closing animation phase while present remains true. Both become false after the animation or fallback timer completes.
onAnimationEndrequired	(e: AnimationEvent) => void	—	React-synthetic onAnimationEnd callback for consumers that do not pass a ref. When a ref is provided this handler is a no-op; the hook's native listener handles completion and filters bubbling child events.

Examples

Basic Toggle

Preview

tsx

1 "use client";2 3 import { useRef, useState } from "react";4 import { usePresence } from "@/hooks/use-presence";5 6 export default function UsePresenceBasicExample() {7   const [open, setOpen] = useState(false);8   const contentRef = useRef<HTMLDivElement>(null);9   const { present } = usePresence({ open, ref: contentRef });10 11   return (12     <div className="flex flex-col gap-4">13       <button14         type="button"15         onClick={() => setOpen((v) => !v)}16         className="w-fit font-mono text-sm border border-border px-3 py-1.5 bg-background hover:bg-muted transition-colors"17       >18         {open ? "Hide" : "Show"}19       </button>20 21       {present && (22         <div23           ref={contentRef}24           data-state={open ? "open" : "closed"}25           className="w-48 border border-border bg-muted p-4 font-mono text-sm motion-safe:data-[state=open]:animate-[fade-in_0.15s_ease-out] motion-safe:data-[state=closed]:animate-[fade-out_0.15s_ease-in_forwards]"26         >27           Animated content28         </div>29       )}30 31       <span className="font-mono text-xs text-muted-foreground">32         open: {String(open)} · present: {String(present)}33       </span>34     </div>35   );36 }37

Tooltip Hover

Preview

tsx

1 "use client";2 3 import { type KeyboardEvent, useId, useRef, useState } from "react";4 import { usePresence } from "@/hooks/use-presence";5 6 export default function UsePresenceTooltipExample() {7   const [open, setOpen] = useState(false);8   const tooltipId = useId();9   const tooltipRef = useRef<HTMLDivElement>(null);10   const { present } = usePresence({ open, ref: tooltipRef });11   const openTooltip = () => setOpen(true);12   const closeTooltip = () => setOpen(false);13   const closeOnEscape = (event: KeyboardEvent<HTMLButtonElement>) => {14     if (event.key !== "Escape") return;15     event.preventDefault();16     setOpen(false);17   };18 19   return (20     <div className="flex items-center justify-center py-12">21       {/* biome-ignore lint/a11y/noStaticElementInteractions: the non-focusable hover region keeps the tooltip hoverable while keyboard access stays on the button. */}22       <div className="relative inline-block" onMouseEnter={openTooltip} onMouseLeave={closeTooltip}>23         <button24           type="button"25           aria-describedby={present ? tooltipId : undefined}26           onFocus={openTooltip}27           onBlur={closeTooltip}28           onKeyDown={closeOnEscape}29           className="font-mono text-sm border border-border px-3 py-1.5 bg-background hover:bg-muted transition-colors"30         >31           Hover me32         </button>33 34         {present && (35           <div36             ref={tooltipRef}37             id={tooltipId}38             role="tooltip"39             data-state={open ? "open" : "closed"}40             className="absolute left-1/2 -translate-x-1/2 top-full mt-1.5 z-[var(--z-popover)] whitespace-nowrap rounded-sm border border-border bg-background px-2 py-1 font-mono text-xs motion-safe:data-[state=open]:animate-[slide-in_0.15s_ease-out] motion-safe:data-[state=closed]:animate-[slide-out_0.15s_ease-in_forwards]"41           >42             Terminal tooltip ▸43           </div>44         )}45       </div>46     </div>47   );48 }49

Notes

State machine

Uses a three-phase state machine (hidden → open → closing → hidden). Phase transitions happen synchronously during render so the element is in the DOM before any useLayoutEffect runs in child components.

CSS animation pattern

Pair with data-state attribute and CSS @keyframes. Set data-state="open"|"closed" and use data-[state=open]:animate-[...] / data-[state=closed]:animate-[...] for enter/exit animations.

Used by

Built into FloatingPanel (the shared anchored-surface primitive) and DialogShell. Popover, Select, and Tooltip inherit presence transitions through FloatingPanel; CommandPaletteContent inherits through DialogShell.

Source

Highlighted source loads after this disclosure opens. Browse the source repository.