Flip Card

Installation#

CLI

npx shadcn@latest add https://hantui-theta.vercel.app/r/flip-card.json

Manual

1. Install the dependencies

   npmpnpmbunyarn

   npm install clsx motion tailwind-merge

2. Add the shared helpers

   Components use cn() from lib/utils.ts and the motion tokens below. See Installation if you have not set them up yet.

   lib/motion.ts

   import type { Transition, Variants } from "motion/react";
   
   /** Durations in seconds. */
   export const duration = {
     instant: 0.1,
     quick: 0.18,
     base: 0.28,
     slow: 0.45,
   } as const;
   
   /** Cubic-bezier curves. */
   export const ease = {
     /** Entering, UI response. */
     out: [0.22, 1, 0.36, 1],
     /** Moving on screen. */
     inOut: [0.65, 0, 0.35, 1],
     /** Sheets and the mobile menu. */
     drawer: [0.32, 0.72, 0, 1],
   } as const;
   
   /** Everyday UI: presses, icon swaps, popovers and modals. Exits run at `exitFactor` of the enter. */
   export const ui = {
     press: { scale: 0.96, duration: 0.12 },
     icon: { type: "spring", duration: 0.3, bounce: 0 },
     popover: { duration: 0.18, ease: ease.out },
     modal: { duration: 0.24, ease: ease.out },
     exitFactor: 0.6,
   } as const;
   
   /** Once-per-visit motion on the landing page: hero letters, the reel and the afterimage. */
   export const kinetic = {
     heroLetter: { duration: 0.6, ease: ease.out },
     /** Delay per letter, eased so the wave slows toward the end. */
     heroStep: 0.035,
     reelSwap: { type: "spring", duration: 0.5, bounce: 0.1 },
     /** Two afterimages: lag in seconds and opacity of each. */
     ghost: { lag: [0.04, 0.09], opacity: [0.14, 0.06] },
   } as const;
   
   /** Spring presets. */
   export const spring = {
     snappy: { type: "spring", stiffness: 500, damping: 30 },
     smooth: { type: "spring", stiffness: 260, damping: 26 },
     bouncy: { type: "spring", stiffness: 300, damping: 15 },
   } as const satisfies Record<string, Transition>;
   
   /** Stagger between siblings, in seconds (0.03–0.06). */
   export const stagger = {
     tight: 0.03,
     base: 0.045,
     loose: 0.06,
   } as const;
   
   /** Blur + fade + y-offset. Falls back to a plain fade under reduced motion. */
   export function enterVariants(reduceMotion?: boolean | null, y = 8): Variants {
     if (reduceMotion) {
       return {
         hidden: { opacity: 0 },
         visible: { opacity: 1, transition: { duration: duration.base } },
         exit: { opacity: 0, transition: { duration: duration.quick } },
       };
     }
     return {
       hidden: { opacity: 0, y, filter: "blur(4px)" },
       visible: {
         opacity: 1,
         y: 0,
         filter: "blur(0px)",
         transition: { duration: duration.base, ease: ease.out },
       },
       exit: {
         opacity: 0,
         y: -y / 2,
         filter: "blur(4px)",
         transition: { duration: duration.quick, ease: ease.out },
       },
     };
   }
   
   /** Scale 0.96 → 1 for popovers, menus and dialogs. */
   export function overlayVariants(reduceMotion?: boolean | null): Variants {
     if (reduceMotion) {
       return {
         hidden: { opacity: 0 },
         visible: { opacity: 1, transition: { duration: duration.quick } },
         exit: { opacity: 0, transition: { duration: duration.instant } },
       };
     }
     return {
       hidden: { opacity: 0, scale: 0.96, filter: "blur(2px)" },
       visible: {
         opacity: 1,
         scale: 1,
         filter: "blur(0px)",
         transition: { duration: duration.quick, ease: ease.out },
       },
       exit: {
         opacity: 0,
         scale: 0.96,
         filter: "blur(2px)",
         transition: { duration: duration.instant + 0.02, ease: ease.out },
       },
     };
   }
   
   /** Parent variants that stagger their children in. */
   export function staggerVariants(gap: number = stagger.base, delayChildren = 0): Variants {
     return {
       hidden: {},
       visible: { transition: { staggerChildren: gap, delayChildren } },
       exit: { transition: { staggerChildren: gap / 2, staggerDirection: -1 } },
     };
   }

   Show all 113 lines

3. Copy the source

   components/ui/flip-card/flip-card.tsx

   "use client";
   
   import { useState, type ComponentProps, type MouseEvent, type ReactNode } from "react";
   import { motion, useReducedMotion } from "motion/react";
   import { cn } from "@/lib/utils";
   import { duration } from "@/lib/motion";
   
   export interface FlipCardProps
     extends Omit<ComponentProps<"button">, "children" | "onAnimationStart" | "onDrag" | "onDragStart" | "onDragEnd"> {
     /** Front face. Keep it non-interactive: the whole card is the flip button. */
     front: ReactNode;
     /** Back face. */
     back: ReactNode;
     /** Controlled flipped state. */
     flipped?: boolean;
     /** Initial flipped state when uncontrolled. @default false */
     defaultFlipped?: boolean;
     /** Called when the card flips. */
     onFlippedChange?: (flipped: boolean) => void;
     /** Flip around the vertical axis (side to side) or the horizontal axis (top over bottom). @default "y" */
     axis?: "y" | "x";
   }
   
   const FLIP = { type: "spring", stiffness: 170, damping: 22, mass: 1 } as const;
   
   export function FlipCard({
     front,
     back,
     flipped,
     defaultFlipped = false,
     onFlippedChange,
     axis = "y",
     className,
     onClick,
     ...props
   }: FlipCardProps) {
     const reduceMotion = useReducedMotion();
     const [internal, setInternal] = useState(defaultFlipped);
     const isFlipped = flipped ?? internal;
     const rotate = axis === "y" ? "rotateY" : "rotateX";
   
     const toggle = (event: MouseEvent<HTMLButtonElement>) => {
       onClick?.(event);
       if (event.defaultPrevented) return;
       if (flipped === undefined) setInternal(!isFlipped);
       onFlippedChange?.(!isFlipped);
     };
   
     // Each face hides its back; the back face starts turned away so the flip reveals it.
     const face = "col-start-1 row-start-1 [backface-visibility:hidden] [-webkit-backface-visibility:hidden]";
   
     return (
       <button
         type="button"
         aria-pressed={isFlipped}
         onClick={toggle}
         className={cn(
           "relative block cursor-pointer rounded-2xl text-left outline-none [perspective:1400px] focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
           className,
         )}
         {...props}
       >
         {/* Switching variants replays every key, so the mid-turn dip in scale happens on each flip. */}
         <motion.span
           className="grid [transform-style:preserve-3d]"
           initial={false}
           variants={{
             front: { [rotate]: 0, scale: [1, 0.94, 1] },
             back: { [rotate]: 180, scale: [1, 0.94, 1] },
           }}
           animate={reduceMotion ? undefined : isFlipped ? "back" : "front"}
           transition={{ ...FLIP, scale: { duration: 0.55, times: [0, 0.5, 1], ease: "easeInOut" } }}
         >
           <motion.span
             className={cn(face, "block")}
             aria-hidden={isFlipped}
             initial={false}
             animate={reduceMotion ? { opacity: isFlipped ? 0 : 1 } : undefined}
             transition={{ duration: duration.base }}
           >
             {front}
           </motion.span>
           {/* The back starts turned away. Its rotation is a Motion value rather than a class, so server markup
               never depends on the reduced-motion setting; with reduced motion it faces front and crossfades. */}
           <motion.span
             className={cn(face, "block")}
             aria-hidden={!isFlipped}
             initial={false}
             animate={reduceMotion ? { [rotate]: 0, opacity: isFlipped ? 1 : 0 } : { [rotate]: 180, opacity: 1 }}
             transition={{ duration: duration.base, [rotate]: { duration: 0 } }}
           >
             {back}
           </motion.span>
         </motion.span>
         <span className="sr-only">{isFlipped ? ", showing the back. Press to show the front." : ". Press to show the back."}</span>
       </button>
     );
   }

   Show all 98 lines

Usage#

import { FlipCard } from "@/components/ui/flip-card/flip-card";

export function Pass() {
  return <FlipCard className="w-80" front={<PassFront />} back={<PassBack />} />;
}

API reference#

Accessibility#

• The whole card is a toggle button (aria-pressed); the hidden face is aria-hidden so only the visible side is read.
• Keep faces free of links and buttons. If a face needs them, control `flipped` from your own button instead.
• With reduced motion enabled, the faces crossfade instead of turning over.