Fluid Component Morphing for React Interfaces

React Morpheus preserves spatial contact from original cmponent to final intraction. This makes ui state feel grounded an intuitive.

View GitHub

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

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
      direction="bottom"
      anchor={MorphAnchor.TopMiddle}
      expanded={expanded}
      onClose={() => setExpanded(false)}
      overlayColor="#0f172a"
      overlayOpacity={0.18}
      overlayBlur={3}
      overlayZIndex={1200}
      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
`direction`	`"top" \| "right" \| "bottom" \| "left"`	Required	Where the panel opens from. Also chooses the default anchor when `anchor` is omitted.
`anchor`	`MorphAnchor`	Optional	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.
`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

Do not place Morpheus inside a container that clips overflow, such as overflow: hidden, overflow: clip, or scroll containers. The expanded surface is positioned from the local source element and can extend outside its original container while animating.

Stacking

overlayZIndex controls the expanded morph 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, directions, 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.