Fluid Component Morphing for React Interfaces

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.

Installation

bun add react-morpheus cuelume

npm i react-morpheus cuelume

yarn add react-morpheus cuelume

Cuelume is a required peer dependency; sound playback remains opt-in. It synthesizes cues with the Web Audio API, so React Morpheus does not bundle audio files.

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)}
      openSound="bloom"
      closeSound="droplet"
      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.

What Morpheus Animates

Morpheus measures the first HTML element rendered by collapsedContent and expandedContent, then animates between these values:

Border style is copied from each endpoint and switches rather than interpolating smoothly. Other CSS properties, such as box shadow, filter, typography, margin, and padding, are not independently interpolated.

Apply the surface background, border, and radius to the root element of each content state. Morpheus reads their computed CSS values, so styles from classes, stylesheets, and inline declarations are all supported.

Sounds

Use openSound and closeSound to add Cuelume cues to the controlled state transition. React Morpheus calls Cuelume directly; you do not need to call bind() or play() yourself.

<Morpheus
  expanded={expanded}
  openSound="bloom"
  closeSound="droplet"
  // ...the remaining props
/>

Each configured cue plays once when expanded changes. The initial render is silent, including when expanded is initially true. Omit either prop to keep that direction silent.

Both props accept Cuelume's SoundName values:

arrival, bloom, chime, droplet, error, loading, page, press, pulse, ready, release, scan, sparkle, success, tick, toggle, and whisper.

Props

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.