@markoradak/folder-card

Animated folder-style cards for React. FLIP spring expansion, 3D lid rotation, SVG notch masks, and a render props API.

Install

npm install @markoradak/folder-card motion

Quick start

import {
  FolderCardGroup,
  FolderCard,
  FolderCardItem,
} from "@markoradak/folder-card";
import "@markoradak/folder-card/styles.css";

function App() {
  return (
    <FolderCardGroup>
      <FolderCard
        id="example"
        renderLid={() => (
          <div style={{ padding: 24 }}>
            <h3>Project Alpha</h3>
            <p>Click to expand</p>
          </div>
        )}
        renderDetail={(close) => (
          <div style={{ padding: 32 }}>
            <h2>Project Alpha</h2>
            <FolderCardItem>
              <p>Stagger-animated content.</p>
            </FolderCardItem>
            <button onClick={close}>Close</button>
          </div>
        )}
      />
    </FolderCardGroup>
  );
}

Features

• FLIP spring animation — Cards spring from grid position to centered dialog using Motion physics.
• 3D lid rotation — Perspective-correct rotation on any edge (bottom, top, left, right, or auto).
• SVG notch mask — Folder-style tab cutouts at any corner or edge center with configurable radii.
• Render props API — Full control over card face, detail content, and tab. No opinionated markup.
• Stagger animations — FolderCardItem wraps content for automatic staggered fade-in.
• CSS variable theming — Override --fc-* variables for colors, radii, shadows, and transitions.

Components

<FolderCardGroup>

Wraps all cards and manages shared state (which card is open, spring config, etc).

Prop	Type	Default	Description
springConfig	{ stiffness?: number; damping?: number }	{ stiffness: 320, damping: 42 }	Spring physics for position/size and lid rotation
dialogViewportPadding	number	32	Padding (px) between dialog and viewport edge
contentRevealDelay	number	200	Delay (ms) before dialog content fades in
openAngle	number	per-hinge default	Override the default open angle (deg) for lid rotation
backdropDuration	number	0.25	Duration (s) of backdrop fade
exitDuration	number	0.15	Duration (s) of content fade-out on close
fadeLid	boolean	false	Fade lid out instead of 3D rotation
dialogMinWidth	number	1000	Minimum target width (px) the dialog tries to reach. Content wider than this grows freely up to the viewport.
backdropClassName	string	—	Class name for the backdrop element
dialogClassName	string	—	Class name for the dialog element
onOpen	(id: string) => void	—	Called when a card opens
onClose	(id: string) => void	—	Called when a card closes

<FolderCard>

An individual card with a lid face and expandable detail.

Prop	Type	Default	Description
id	string	required	Unique identifier
renderLid	() => ReactNode	required	Card face / expanded lid content
renderDetail	(close: () => void) => ReactNode	required	Expanded dialog content. Rendered into two React trees (a hidden measurement tree and the visible dialog) — every component inside mounts twice. Keep side-effect-free; lift data fetching and subscriptions to a parent.
renderTab	() => ReactNode	—	Tab notch content
ariaLabel	string	—	Accessible label for the expanded dialog
className	string	—	Class name for the card button
style	CSSProperties	—	Inline styles for the card wrapper
perspective	number	1800	Perspective depth (px) for 3D rotation
hingeSide	'auto' | 'bottom' | 'top' | 'left' | 'right'	'auto'	Which edge the lid hinges on
notchPosition	NotchPosition	'top-right'	Where the tab notch sits (8 positions)
notchOuterRadius	number	card radius	Outer concave radius of the notch cutout
notchInnerRadius	number	cardRadius * 0.7	Inner inverted radius of the notch cutout
liveRadius	boolean	false	Observe --fc-radius changes reactively

<FolderCardItem>

Wraps content inside renderLid or renderDetail for staggered fade-in animation.

CSS variables

Import the base stylesheet and override variables to theme:

@import "@markoradak/folder-card/styles.css";

:root {
  --fc-radius: 20px;
  --fc-card-bg: #ffffff;
  --fc-foreground: #0a0a0a;
  --fc-border: rgba(0, 0, 0, 0.1);
  --fc-muted: rgba(0, 0, 0, 0.45);
  --fc-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.08);
  --fc-shadow-lg: 0 8px 30px rgba(0, 0, 0, 0.12);
  --fc-backdrop-bg: rgba(0, 0, 0, 0.5);
  --fc-dialog-shadow: 0 25px 60px rgba(0, 0, 0, 0.25);
  --fc-focus-ring: rgba(0, 0, 0, 0.2);
  --fc-lid: color-mix(in srgb, var(--fc-foreground) 6%, var(--fc-card-bg));
  --fc-lid-border: transparent;           /* advanced: fallback only */
  --fc-lid-back: /* gradient */;          /* advanced: fallback only */
  --fc-transition-duration: 300ms;
  --fc-transition-easing: ease-out;
}

Dark mode is applied automatically via @media (prefers-color-scheme: dark). To integrate with a class-based theme switcher (e.g. next-themes), override the variables inside your own .dark selector.

Development

This repository is a pnpm + Turborepo monorepo:

packages/
  react/          @markoradak/folder-card — the published package
apps/
  web/            Next.js demo + documentation site

Requires Node 18+ and pnpm 10+.

pnpm install
pnpm dev          # run the demo site + package in watch mode
pnpm build        # build the package
pnpm typecheck    # typecheck all workspaces

cd packages/react
pnpm test         # run the package test suite

License

MIT