Morph Surface

Morph Surface is an unstyled layout primitive for changing the dimensions and content of one persistent surface. The same surface grows, shrinks, clips, and reveals around a shared center origin by default, while styling, state, focus behavior, and product actions remain consumer-owned.

Preview

Reduce motion:Off

Inspect

Installation

Motion

npx shadcn@latest add @sona-ui/morph-surface

Basic usage

morphing-panel.tsx

import MorphSurface from "@/components/ui/morph-surface/morph-surface";
 
export function MorphingPanel({ view }: { view: "compact" | "expanded" }) {
return (
  <MorphSurface.Root value={view} className="rounded-xl bg-card shadow-lg">
    {view === "compact" ? <div>Summary</div> : <div>Expanded controls</div>}
  </MorphSurface.Root>
);
}

Usage


"use client";
 
import { ArrowLeft, ArrowRight } from "lucide-react";
import { useState } from "react";
 
import MorphSurface from "@/components/ui/morph-surface/morph-surface";
 
export default function MorphSurfaceDemo() {
  const [view, setView] = useState("compact");
 
  return (
    <MorphSurface.Root
      value={view}
      className="rounded-2xl bg-card shadow-smooth-ring-lg"
    >
      {view === "compact" ? (
        <div className="p-2">
          <button
            type="button"
            onClick={() => setView("expanded")}
            className="flex items-center gap-3 rounded-xl px-3 py-2 text-sm outline-none transition-colors bg-secondary hover:bg-muted hover:cursor-pointer focus-visible:ring-2 focus-visible:ring-ring"
          >
            <span className="font-medium">Review changes</span>
            <ArrowRight
              aria-hidden="true"
              className="size-4 text-muted-foreground"
            />
          </button>
        </div>
      ) : (
        <div className="w-80 p-4 bg-secondary">
          <div className="flex items-start gap-3">
            <button
              type="button"
              aria-label="Return to summary"
              onClick={() => setView("compact")}
              className="grid size-8 shrink-0 place-items-center rounded-lg text-muted-foreground outline-none  transition-colors hover:bg-muted hover:text-foreground hover:cursor-pointer focus-visible:ring-2 focus-visible:ring-ring"
            >
              <ArrowLeft aria-hidden="true" className="size-4" />
            </button>
            <div>
              <h3 className="font-medium text-sm">Three files changed</h3>
              <p className="mt-1 text-muted-foreground text-sm leading-6">
                The same surface grows around its center while its content
                changes in place.
              </p>
            </div>
          </div>
        </div>
      )}
    </MorphSurface.Root>
  );
}

API

Property	Type	Default	Description
`value`	`string`	`required`	A value that identifies the current content state and starts a new morph when it changes.
`children`	`ReactNode`	`required`	The current content rendered inside the persistent surface.
`transition`	`Transition`	`motionTransition.spatial`	The transition used when the persistent surface changes size.
`contentTransition`	`Transition`	`motionTransition.enter`	The transition used when the content changes.
`contentScale`	`number`	`0.96`	The scale from which changed content resolves inside the surface.
`origin`	`MorphSurfaceOrigin`	`"center"`	The shared origin used to grow, shrink, reveal, and scale the surface content.
`anchorClassName`	`string`	`undefined`	Additional classes for the stable layout anchor around the surface.
`clipClassName`	`string`	`undefined`	Additional classes for the internal clipping layer.
`contentClassName`	`string`	`undefined`	Additional classes for the persistent content wrapper.
`reducedMotion`	`MorphSurfaceReducedMotion`	`"user"`	Controls whether the surface follows, forces, or ignores reduced motion.

Accessibility

Morph Surface follows the user's reduced-motion preference by default and applies dimension and content changes immediately when motion is reduced. Consumers remain responsible for focus movement, accessible labels, and announcing meaningful state changes.

Styling

The primitive carries no visual surface styles. Apply the background, radius, and elevation to the persistent root with className. Put state-specific spacing and dimensions on the content rendered inside it. An internal clip layer preserves the root elevation while clipping content to the inherited radius.

Contact

Found a bug or need help using this component? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this component in personal and commercial projects.

Sona UI