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

Morpheus.Screencast.mp4

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:

Area	Animated values
Geometry	Width, height, and the anchored screen position
Surface	Background color, border color, border width, and border radius
Content	Opacity, position, and uniform scale so content keeps its proportions

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

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.
openSound	SoundName	Optional	Cuelume sound played once when expanded changes to true.
closeSound	SoundName	Optional	Cuelume sound played once when expanded changes to false.
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.