Plinth

Installation

Plinth has one peer dependency: motion (the modern Motion library, formerly Framer Motion). Install both alongside React.

npm install @beauhawkinson/plinth motion

Peer versions: react ^18 || ^19, react-dom ^18 || ^19, motion ^12.

Quickstart

Import the component and render it. The default stylesheet ships bundled with the component and injects itself on mount — no separate CSS import to remember.

import { Plinth } from "@beauhawkinson/plinth";

export default function Example() {
  return <Plinth count={6} />;
}

To customize the look, see Styling.

In a Next.js App Router project

// app/page.tsx
import { Plinth } from "@beauhawkinson/plinth";

export default function Page() {
  return (
    <main className="flex min-h-screen items-center justify-center">
      <Plinth />
    </main>
  );
}

Anatomy

Each card is a six-faced 3D box. Every face is a real DOM element you can target. The data-face attribute on each one is part of the stable public API — it will not change between versions.

• frontThe card you see. Style it with faceStyles.front or [data-face="front"].
• backMirror of the front, used during deep tilts. Rarely visible.
• topHeight equals depth. Visible when rotateX is negative (leaning back).
• bottomHeight equals depth. Visible from below. Catches shadow tint.
• left / rightWidth equals depth. Visible based on rotateY tilt.

The outer container is a <fieldset> element with class .plinth-stack-fieldset. Each pillar wrapper carries .plinth-card-wrapper, and every face has .plinth-face plus .plinth-face-{name}.

Hover Physics

The hover effect comes from two overlapping influence curves centered on the cursor. Both curves are Gaussian — they peak at 1 over the cursor and fall off smoothly with distance.

• The broad curve drives scaleDip across the whole row — usually a negative value, so cards squish slightly as the cursor moves over them.
• The narrow curve drives scaleBoost and liftAmount — a tight peak that grows the hovered card and lifts it upward.

Both values then pass through a single motion spring, so animations feel weighted. Tune the spring for snappier or softer behavior.

<Plinth
  hover={{
    spring: { stiffness: 220, damping: 28, mass: 0.2 },
    scaleDip:      -0.15,  // adjacent cards squish slightly
    scaleBoost:     1.4,   // hovered card grows taller
    falloff:        1.6,   // broad zone of influence
    narrowFalloff:  2,     // tight zone for the lift
  }}
/>

Sizing & Responsiveness

Plinth sizes itself to fit its cards. The total visible width is roughly cardWidth + (count − 1) × peek, so a stack of 8 cards at 384px width with the default peek of 64 takes about 832px.

The container does not shrink to fit narrower viewports automatically. For mobile-friendly layouts, swap count and cardWidth based on a media query:

"use client";

import { Plinth } from "@beauhawkinson/plinth";
import { useEffect, useState } from "react";

function useIsMobile() {
  const [isMobile, setIsMobile] = useState(false);
  useEffect(() => {
    const mq = window.matchMedia("(max-width: 640px)");
    setIsMobile(mq.matches);
    const handler = (e: MediaQueryListEvent) => setIsMobile(e.matches);
    mq.addEventListener("change", handler);
    return () => mq.removeEventListener("change", handler);
  }, []);
  return isMobile;
}

export default function Responsive() {
  const isMobile = useIsMobile();
  return (
    <Plinth
      count={isMobile ? 4 : 8}
      cardWidth={isMobile ? 240 : 384}
    />
  );
}

TypeScript

The package ships with full type definitions. All public types are exported from the package root:

import type {
  PlinthProps,
  HoverConfig,
  FaceStyles,
  FaceName,
} from "@beauhawkinson/plinth";

// FaceName = "front" | "back" | "top" | "bottom" | "left" | "right"
// FaceStyles = Partial<Record<FaceName, string>>

const myStyles: FaceStyles = {
  front: "bg-white border",
  top: "bg-stone-100",
};

Browser Support & Accessibility

• Requires CSS 3D transforms (universally supported) and modern ResizeObserver (Safari 13.1+, Chrome 64+, Firefox 69+).
• The default stylesheet uses oklch() colors — supported in Chrome 111+, Safari 15.4+, Firefox 113+. If you support older browsers, provide your own stylesheet with fallback colors.
• The hover effect is mouse-driven. On touch devices the cards sit at their resting position with no animation — by design, since touch has no hover. Plan content accordingly if your stack is interactive.
• Plinth is a visual / decorative component. The cards are not focusable, do not capture keyboard input, and do not announce themselves to screen readers. If you need accessible content, render it in a separate, semantic layer (e.g. an off-screen list) and let Plinth handle the visual.

Recipes

A heavily-customized stack with adjusted dimensions, camera, hover, and dark face styling:

<Plinth
  count={8}
  cardWidth={220}
  cardHeight={300}
  rotateX={-18}
  rotateY={-32}
  perspective={1400}
  hover={{
    spring: { stiffness: 220, damping: 28, mass: 0.2 },
    scaleDip: -0.15,
    scaleBoost: 1.4,
    falloff: 1.6,
    narrowFalloff: 2,
  }}
  faceStyles={{
    front: "bg-zinc-900 text-zinc-50",
    top: "bg-zinc-800",
    bottom: "bg-zinc-950",
    left: "bg-zinc-700",
    right: "bg-zinc-700",
  }}
/>

Roadmap

Planned improvements as the library evolves — no version commitments, just a public record of what's on the horizon.

• prefers-reduced-motionDisable hover physics when the user has reduced motion enabled.
• oklch fallbacksPair every oklch() declaration with an rgb/hex fallback so older browsers degrade gracefully.
• Vertical orientationAn orientation="vertical" prop for stacks that descend top-to-bottom.
• Touch-aware modeOpt-in ambient animation or tap-to-focus interaction for touch devices, since hover doesn't fire on touch.
• Keyboard navigationAn interactive prop that makes the stack a single tabstop with arrow keys to move the lifted card.
• renderCard propBring back the render prop for putting custom content inside each front face.

Have a request or a use case the current API doesn't cover? Open an issue on GitHub.