React Morpheus

A controlled React component for morphing one UI state into another.

React Morpheus exists for interfaces where a control should become the next piece of UI instead of opening a detached popover. The component keeps the source surface, destination surface, and overlay explicit. Your app still owns state and content; Morpheus owns the measured transition between those two surfaces.

Demo

https://github.com/user-attachments/assets/f90e7096-f587-4793-8e80-476cf844569d

Installation

bun add react-morpheus

npm i react-morpheus

yarn add react-morpheus

Usage

Import the component and stylesheet, keep the open state in your app, and pass both surfaces to Morpheus.

import { useState } from "react";
import {
  Morpheus,
  MorphAnchor,
  morphSpringPresets,
} from "react-morpheus";
import "react-morpheus/style.css";

function Example() {
  const [expanded, setExpanded] = useState(false);
  const source = (
    <button type="button" onClick={() => setExpanded(true)}>
      Open menu
    </button>
  );

  return (
    <Morpheus
      anchor={MorphAnchor.TopMiddle}
      expanded={expanded}
      onClose={() => setExpanded(false)}
      overlayColor="#0f172a"
      overlayOpacity={0.18}
      overlayBlur={3}
      overlayZIndex={1200}
      viewportPadding={16}
      spring={morphSpringPresets.smooth}
      collapsedContent={source}
      expandedContent={
        <section>
          <h2>San Francisco</h2>
          <p>Context, actions, and details live here.</p>
          <button type="button" onClick={() => setExpanded(false)}>
            Close
          </button>
        </section>
      }
    />
  );
}

Morpheus does not manage its own open state. Opening is the responsibility of the source component's own click handler. Overlay clicks call onClose; update your controlled state there. Use beforeClose and afterClose for work that should run around the closing animation.

Props

| Prop | Type | Required | Notes | | --- | --- | --- | --- | | anchor | MorphAnchor | Required | The edge or point that stays visually anchored. | | expanded | boolean | Required | Controlled open state owned by your app. | | onClose | () => void | Optional | Called when the overlay requests closing. Use it to update your controlled open state. | | beforeClose | () => void | Optional | Called when the closing animation starts, after expanded has changed to false. Useful for close-intent side effects. | | afterClose | () => void | Optional | Called after the closing animation completes. | | collapsedContent | ReactNode | Required | The source surface Morpheus measures, renders, and uses as the opener. | | expandedContent | ReactNode | Required | The destination surface Morpheus measures and animates into. | | className | string | Optional | Classes applied to the root wrapper. Useful for block layout and responsive width constraints. | | shellClassName | string | Optional | Classes applied directly to the animated shell, including when it is portalled. | | portalContainer | HTMLElement \| null | Optional | Portal root for the expanded surface. Defaults to document.body after mount; pass null for legacy inline rendering. | | viewportPadding | number | Optional | Minimum viewport gutter for the expanded shell. Defaults to 16. | | overlayColor | string | Optional | Backdrop color shown while expanded. | | overlayOpacity | number | Optional | Backdrop opacity from 0 to 1. | | overlayBlur | number | Optional | Backdrop blur in pixels. | | overlayZIndex | number | Optional | Stacking level for the expanded surface. Defaults to 1000; the overlay renders one layer below it. | | spring | Transition | Optional | Framer Motion transition. Pass your own transition or use morphSpringPresets. |

Pitfalls

Responsiveness

Let the collapsed trigger keep its natural size. Morpheus reads that box before animating to the expanded surface.

Put responsive width rules on className, such as viewport-bound max widths, so the animated shell has stable constraints on narrow screens.

Pick an anchor that matches the source location. Top anchors feel right for menus opening below a trigger; bottom anchors feel right for surfaces opening upward; middle anchors feel better for centered inspectors or command surfaces.

Parent Container Overflow

Expanded surfaces and their overlays portal to document.body by default, so they can escape clipped, transformed, and independently stacked ancestors. The collapsed source remains in its original layout position. Pass another document-level portalContainer when needed, or null to opt into the legacy inline behavior.

Targets are clamped to the viewport using viewportPadding. When their natural size is larger than the available viewport, the shell stays bounded and becomes scrollable after the opening animation settles.

Stacking

overlayZIndex controls the portalled expanded surface. The overlay renders one layer below it so apps can move the whole morphing stack above their own chrome. Without this prop, Morpheus uses surface 1000 and overlay 999.

Development

example.html is a small local playground for trying Morpheus in a browser without setting up an app shell. Use it to check the default interaction, anchors and overlay behavior while changing the component.

Scripts

• bun run build builds declarations, bundled ESM output, and CSS.
• bun run check runs TypeScript without emitting files.
• bun run publish:npm builds and publishes to npm.
• bun run release:patch bumps the patch version, builds, tags, and publishes.
• bun run release:minor bumps the minor version, builds, tags, and publishes.
• bun run release:major bumps the major version, builds, tags, and publishes.

Credits

Inspired by Family Wallet and Benji Taylor's Family Values post.

License

Released under the MIT License.