useGsapPresence

The GSAP exit bridge, implemented once and reused by every Base UI wrapper (Modal, Popover, Tooltip). Base UI can auto-detect a CSS transition before unmounting, but not a JS animation — so on close this hook asks Base UI to keep the node mounted, runs the GSAP exit, and calls unmount() itself when the tween finishes. It is Base-UI-agnostic: it only needs an actions object exposing unmount().

Feel A popup leaves the way it arrived, instead of vanishing mid-animation.

Modal, Popover, and Tooltip all run on this one hook. Base UI detects CSS transitions before unmount, but not GSAP; this bridges the gap.

Or let the agent fetch it: get_component("use-gsap-presence") on the Echo MCP server.

Installation

npm install echo-ui-core

This one ships in the echo-ui-core package rather than being copied into your project — npx echo-ui-cli init installs it for you. Import it from echo-ui-core/presence.

At a glance

Weight: 1.9 KB · 28.6 KB with what it imports (minified and gzipped; React not counted)
Needs: gsap
Reduced motion: Enter and exit follow the tokens' collapse — bloom and summon become a fade — and the node still unmounts when it ends.

Usage

tsx

import type { RefObject } from "react";
import { Dialog } from "@base-ui/react/dialog";
import { useGsapPresence } from "echo-ui-core/presence";

const p = useGsapPresence();
return (
  <Dialog.Root
    open={p.open}
    onOpenChange={p.onOpenChange}
    actionsRef={p.actionsRef as RefObject<Dialog.Root.Actions | null>}
  >
    <Dialog.Portal>
      <Dialog.Popup ref={p.popupRef}>…</Dialog.Popup>
    </Dialog.Portal>
  </Dialog.Root>
);

Examples

Wire a Base UI Root

Spread the three controlled props; attach popupRef to the animated popup. The hook types its actions as the one method it calls (`unmount`), so narrow them to the Root's own Actions type at the call site.

tsx

const p = useGsapPresence();
<Dialog.Root
  open={p.open}
  onOpenChange={p.onOpenChange}
  actionsRef={p.actionsRef as React.RefObject<Dialog.Root.Actions | null>}
>
  <Dialog.Popup ref={p.popupRef}>…</Dialog.Popup>
</Dialog.Root>

Different enter and exit

Tokens name the timing at both ends.

tsx

const p = useGsapPresence({ enter: "summon", exit: "glitch" });

Motion & sound

Motion tokens: bloom, summon
Reduced motion: Enter and exit follow the tokens' collapse — bloom and summon become a fade — and the node still unmounts when it ends.

Props

useGsapPresence props
Prop	Type	Default
`enter`Motion token for the enter timing: it grows out of what opened it.	`string`	`"bloom"`
`exit`Motion token for the exit timing.	`string`	`"summon"`
`animate`Take over the motion: enter(el, { trigger }) when the popup mounts, exit(el, done, { trigger }) when it closes — call done and it unmounts. Skipped under reduced motion for the plain fade.	`object`
`defaultOpen`Initial open state.	`boolean`	`false`
`onOpened`Called once the enter animation has started.	`function`

Anti-patterns

Never rely on actionsRef alone to hold the element mounted — it does not. The exit only survives because onOpenChange calls details.preventUnmountOnClose(); drop that call and Base UI removes the node mid-tween.
Never also put a CSS transition on the popup's transform or opacity. GSAP owns those properties here, and Base UI's transition auto-detection will race the tween. Transition the backdrop instead.
Never use this with Base UI Select — its ChangeEventDetails has no preventUnmountOnClose, so there is nothing to hold the node. Select animates through [data-starting-style] / [data-ending-style] CSS instead.
Never assert on role="dialog" to test the exit — Base UI drops the role immediately on close while the node is still animating. Target the popup element's class.

Changelog

v0.3.0 · 2026-10-12 · ChangedEvery item needs echo-ui-core 0.3.0 (all components). The drawn device, readability past AA and the design tests live in core, and the components that use them are built against it, so each item now declares echo-ui-core >=0.3.0 <0.4.0. Update core with the items: npm install echo-ui-core@^0.3.0 (or your package manager's), then npx echo-ui-cli update. An item whose files didn't change is the same code under a new version; the 0.2.0 files stay published.
v0.2.0 · 2026-10-04 · ChangedComments only, no behaviour change. Comments in the component source used to cite documents, milestones and ticket numbers from Echo's own planning, none of which exist in your project. The citations are gone and the sentences around them stay. Where a comment was only a citation, it now says what it meant. Three development warnings (HardwareButton's engraved/caption checks and StatusDot's missing-label check) also dropped the ticket code at the end of the message. echo-ui diff will show changes in most items; none of them are to code.
v0.2.0 · 2026-10-04 · ChangedAn item's version is now a function of declared data, not of how the changelog is formatted. The version an item ships under is published once and never rewritten, and it used to be inferred from prose: a regex for a bolded "Breaking" run across the whole unreleased section, and attribution by "does a bullet mention this name in backticks". One breaking entry therefore moved every item that changed that cycle, and an entry explaining that "Menu and Sheet are unchanged here" filed itself as a change to Menu and Sheet — which it really had.
v0.2.0 · 2026-10-04 · ChangedThe agent brief says Echo has not shipped. llms.txt and the MCP server's instructions led with npx echo-ui-cli init, and that name on npm is a reserved stub with no executable — so a model following the brief wrote an install step that fails with npx's own error. The brief now opens with the caveat, and the docs carry it on every surface that shows a command. One switch (CLI_RELEASED) silences all of them at launch, and a test refuses to let one move without the others. Affects all components only in what the brief says about installing them; no item's props, CSS or rendered semantics change.
v0.2.0 · 2026-10-04 · ChangedEcho's home is echo-ui.com. The registry, the docs and the packages all move to it from echo.nawwara.studio. Nothing was published under the old host, so no echo.json anywhere points at it and there is nothing to migrate — this is the last release where that is true.
v0.2.0 · 2026-10-04 · ChangedWeights, line heights, letter-spacing, z-index, border widths and icon sizes come from the theme scales in all components, with the old value as a fallback, so components keep working with echo-ui-core@0.0.1. Strays moved to the nearest step: most by under a pixel; HardwareButton icons are 14/16/20px (were 15/17/19).
v0.2.0 · 2026-10-04 · FixedContent now reflows into a 320px screen (400% zoom) and survives a doubled browser text size (WCAG 1.4.10, 1.4.4), across all components. Select's 180px floor, NumberField's readout, Segmented and Steps as flex items, EmptyState's grid columns, and Avatar's fixed-pixel disc all gave way; Panel counts its padding inside a width you set (box-sizing: border-box), so a <Panel style={{ width: 220 }}> is now 220px wide overall rather than 260px.

Preview