Skip to content

UI Library for Design Engineers. Animated components and effects you can copy and paste into your apps. Free. Open Source.

Add Text 3D Flip component (#937)

Aayush Bharti14d4bb93ab48
diff --git a/apps/www/config/docs.ts b/apps/www/config/docs.ts
index d4e5aa4c..a6bd0769 100644
--- a/apps/www/config/docs.ts
+++ b/apps/www/config/docs.ts
@@ -438,6 +438,12 @@ export const docsConfig: DocsConfig = {
items: [],
label: "New",
},
+ {
+ title: "Text 3D Flip",
+ href: `/docs/components/text-3d-flip`,
+ items: [],
+ label: "New",
+ },
],
},
{
diff --git a/apps/www/content/docs/components/text-3d-flip.mdx b/apps/www/content/docs/components/text-3d-flip.mdx
new file mode 100644
index 00000000..1f4e9484
--- /dev/null
+++ b/apps/www/content/docs/components/text-3d-flip.mdx
@@ -0,0 +1,82 @@
+---
+title: Text 3D Flip
+date: 2026-04-05
+description: A text effect that flips each letter in 3D with a staggered animation on hover.
+author: aayushbharti
+published: true
+---
+
+<ComponentPreview name="text-3d-flip-demo" />
+
+## Installation
+
+<Tabs defaultValue="cli">
+
+<TabsList>
+ <TabsTrigger value="cli">CLI</TabsTrigger>
+ <TabsTrigger value="manual">Manual</TabsTrigger>
+</TabsList>
+<TabsContent value="cli">
+
+```bash
+npx shadcn@latest add @magicui/text-3d-flip
+```
+
+</TabsContent>
+
+<TabsContent value="manual">
+
+<Steps>
+
+<Step>Copy and paste the following code into your project.</Step>
+
+<ComponentSource name="text-3d-flip" />
+
+<Step>Update the import paths to match your project setup.</Step>
+
+</Steps>
+
+</TabsContent>
+
+</Tabs>
+
+## Usage
+
+```tsx showLineNumbers
+import Text3DFlip from "@/components/ui/text-3d-flip"
+```
+
+```tsx showLineNumbers
+<Text3DFlip
+ className="bg-background"
+ textClassName="bg-background text-foreground"
+ flipTextClassName="bg-background text-foreground"
+ rotateDirection="top"
+>
+ Stay hungry, stay foolish
+</Text3DFlip>
+```
+
+## Examples
+
+### Stagger from center
+
+<ComponentPreview name="text-3d-flip-demo-2" />
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------------- | ----------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `children`\* | `ReactNode` | `-` | The content to be displayed and animated |
+| `as` | `ElementType` | `"p"` | HTML element to render the component as |
+| `className` | `string` | `-` | Class name for the main container element |
+| `textClassName` | `string` | `-` | Class name for each letter (visible before flip) |
+| `flipTextClassName` | `string` | `-` | Class name for each letter (revealed after flip) |
+| `staggerDuration` | `number` | `0.05` | Duration of stagger delay between each letter in seconds |
+| `staggerFrom` | `"first" \| "last" \| "center" \| number \| "random"` | `"first"` | Direction to stagger animations from. Use a number to stagger from a specific character index |
+| `transition` | `ValueAnimationTransition \| AnimationOptions` | `{ type: "spring", damping: 30, stiffness: 300 }` | Animation transition configuration from Motion |
+| `rotateDirection` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Direction of 3D rotation on hover |
+
+## Credits
+
+- Credit to [@AayushBharti](https://github.com/AayushBharti)
diff --git a/apps/www/public/llms-full.txt b/apps/www/public/llms-full.txt
index cc6e31e7..7e9ba158 100644
--- a/apps/www/public/llms-full.txt
+++ b/apps/www/public/llms-full.txt
@@ -17152,6 +17152,328 @@ export default function TerminalDemo2() {
+===== COMPONENT: text-3d-flip =====
+Title: Text 3D Flip
+Description: A text effect that flips each letter in 3D with a staggered animation on hover.
+
+--- file: magicui/text-3d-flip.tsx ---
+"use client"
+
+import React, {
+ memo,
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ type ElementType,
+} from "react"
+import {
+ useAnimate,
+ type AnimationOptions,
+ type ValueAnimationTransition,
+} from "motion/react"
+
+import { cn } from "@/lib/utils"
+
+const HAS_SEGMENTER = typeof Intl !== "undefined" && "Segmenter" in Intl
+
+const splitIntoCharacters = (text: string): string[] => {
+ if (HAS_SEGMENTER) {
+ const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" })
+ return Array.from(segmenter.segment(text), ({ segment }) => segment)
+ }
+ return Array.from(text)
+}
+
+const extractTextFromChildren = (children: React.ReactNode): string => {
+ if (children == null) return ""
+ if (typeof children === "string") return children
+ if (typeof children === "number") return String(children)
+
+ if (Array.isArray(children)) {
+ return children.map(extractTextFromChildren).join("")
+ }
+
+ if (React.isValidElement(children)) {
+ const props = children.props as Record<string, unknown>
+ const childText = props.children as React.ReactNode
+ if (childText != null) {
+ return extractTextFromChildren(childText)
+ }
+ }
+
+ return ""
+}
+
+const ROTATION_MAP = {
+ top: "rotateX(90deg)",
+ right: "rotateY(90deg)",
+ bottom: "rotateX(-90deg)",
+ left: "rotateY(-90deg)",
+} as const
+
+const DEFAULT_TRANSITION: ValueAnimationTransition = {
+ type: "spring",
+ damping: 30,
+ stiffness: 300,
+}
+
+interface Text3DFlipProps {
+ children: React.ReactNode
+ as?: ElementType
+ className?: string
+ textClassName?: string
+ flipTextClassName?: string
+ staggerDuration?: number
+ staggerFrom?: "first" | "last" | "center" | number | "random"
+ transition?: ValueAnimationTransition | AnimationOptions
+ rotateDirection?: "top" | "right" | "bottom" | "left"
+}
+
+const Text3DFlip = ({
+ children,
+ as: ElementTag = "p",
+ className,
+ textClassName,
+ flipTextClassName,
+ staggerDuration = 0.05,
+ staggerFrom = "first",
+ transition = DEFAULT_TRANSITION,
+ rotateDirection = "right",
+ ...props
+}: Text3DFlipProps) => {
+ const isAnimatingRef = useRef(false)
+ const isMountedRef = useRef(false)
+ const [scope, animate] = useAnimate()
+
+ const rotationTransform = ROTATION_MAP[rotateDirection]
+
+ useEffect(() => {
+ isMountedRef.current = true
+
+ return () => {
+ isMountedRef.current = false
+ isAnimatingRef.current = false
+ }
+ }, [])
+
+ const text = useMemo(() => {
+ try {
+ return extractTextFromChildren(children)
+ } catch {
+ return ""
+ }
+ }, [children])
+
+ const characters = useMemo(() => {
+ const words = text.split(" ")
+ return words.map((word, i) => ({
+ characters: splitIntoCharacters(word),
+ needsSpace: i !== words.length - 1,
+ }))
+ }, [text])
+
+ const charOffsets = useMemo(() => {
+ const offsets = [0]
+ for (const word of characters) {
+ offsets.push(offsets.at(-1)! + word.characters.length)
+ }
+ return offsets
+ }, [characters])
+
+ const getStaggerDelay = useCallback(
+ (index: number, totalChars: number) => {
+ if (staggerFrom === "first") return index * staggerDuration
+ if (staggerFrom === "last")
+ return (totalChars - 1 - index) * staggerDuration
+ if (staggerFrom === "center") {
+ const center = Math.floor(totalChars / 2)
+ return Math.abs(center - index) * staggerDuration
+ }
+ if (staggerFrom === "random") {
+ const randomIndex = Math.floor(Math.random() * totalChars)
+ return Math.abs(randomIndex - index) * staggerDuration
+ }
+ return Math.abs(staggerFrom - index) * staggerDuration
+ },
+ [staggerFrom, staggerDuration]
+ )
+
+ const handleHoverStart = useCallback(async () => {
+ if (isAnimatingRef.current) return
+ isAnimatingRef.current = true
+
+ try {
+ const totalChars = characters.reduce(
+ (sum, word) => sum + word.characters.length,
+ 0
+ )
+
+ const delays = Array.from({ length: totalChars }, (_, i) =>
+ getStaggerDelay(i, totalChars)
+ )
+
+ await animate(
+ ".text-3d-flip-char",
+ { transform: rotationTransform },
+ {
+ ...transition,
+ delay: (i: number) => delays[i],
+ }
+ )
+
+ if (!isMountedRef.current) return
+
+ await animate(
+ ".text-3d-flip-char",
+ { transform: "rotateX(0deg) rotateY(0deg)" },
+ { duration: 0 }
+ )
+ } finally {
+ if (isMountedRef.current) {
+ isAnimatingRef.current = false
+ }
+ }
+ }, [characters, transition, getStaggerDelay, rotationTransform, animate])
+
+ return (
+ <ElementTag
+ className={cn("relative flex flex-wrap", className)}
+ onMouseEnter={handleHoverStart}
+ ref={scope}
+ {...props}
+ >
+ <span className="sr-only">{text}</span>
+
+ {characters.map((wordObj, wordIndex) => (
+ <span key={wordIndex} className="inline-flex">
+ {wordObj.characters.map((char, charIndex) => (
+ <CharBox
+ key={charOffsets[wordIndex] + charIndex}
+ char={char}
+ textClassName={textClassName}
+ flipTextClassName={flipTextClassName}
+ rotateDirection={rotateDirection}
+ />
+ ))}
+ {wordObj.needsSpace && <span className="whitespace-pre"> </span>}
+ </span>
+ ))}
+ </ElementTag>
+ )
+}
+
+interface CharBoxProps {
+ char: string
+ textClassName?: string
+ flipTextClassName?: string
+ rotateDirection: "top" | "right" | "bottom" | "left"
+}
+
+const SECOND_FACE_TRANSFORMS = {
+ top: "rotateX(-90deg) translateZ(0.5lh)",
+ right:
+ "rotateY(90deg) translateX(50%) rotateY(-90deg) translateX(-50%) rotateY(-90deg) translateX(50%)",
+ bottom: "rotateX(90deg) translateZ(0.5lh)",
+ left: "rotateY(90deg) translateX(50%) rotateY(-90deg) translateX(50%) rotateY(-90deg) translateX(50%)",
+} as const
+
+const FRONT_FACE_TRANSFORMS = {
+ top: "translateZ(0.5lh)",
+ bottom: "translateZ(0.5lh)",
+ left: "rotateY(90deg) translateX(50%) rotateY(-90deg)",
+ right: "rotateY(-90deg) translateX(50%) rotateY(90deg)",
+} as const
+
+const CONTAINER_TRANSFORMS = {
+ top: "translateZ(-0.5lh)",
+ bottom: "translateZ(-0.5lh)",
+ left: "rotateY(90deg) translateX(50%) rotateY(-90deg)",
+ right: "rotateY(90deg) translateX(50%) rotateY(-90deg)",
+} as const
+
+const CharBox = memo(
+ ({
+ char,
+ textClassName,
+ flipTextClassName,
+ rotateDirection,
+ }: CharBoxProps) => (
+ <span
+ className="text-3d-flip-char inline transform-3d"
+ style={{ transform: CONTAINER_TRANSFORMS[rotateDirection] }}
+ >
+ <span
+ className={cn("relative h-[1lh] backface-hidden", textClassName)}
+ style={{ transform: FRONT_FACE_TRANSFORMS[rotateDirection] }}
+ >
+ {char}
+ </span>
+ <span
+ className={cn(
+ "absolute top-0 left-0 h-[1lh] backface-hidden",
+ flipTextClassName
+ )}
+ style={{ transform: SECOND_FACE_TRANSFORMS[rotateDirection] }}
+ >
+ {char}
+ </span>
+ </span>
+ )
+)
+
+CharBox.displayName = "CharBox"
+Text3DFlip.displayName = "Text3DFlip"
+
+export default Text3DFlip
+
+
+===== EXAMPLE: text-3d-flip-demo =====
+Title: Text 3D Flip Demo
+
+--- file: example/text-3d-flip-demo.tsx ---
+import Text3DFlip from "@/registry/magicui/text-3d-flip"
+
+export default function Text3DFlipDemo() {
+ return (
+ <Text3DFlip
+ className="bg-background font-serif text-2xl sm:text-5xl md:text-[56px]"
+ textClassName="bg-background text-foreground"
+ flipTextClassName="bg-background text-foreground"
+ rotateDirection="top"
+ staggerDuration={0.03}
+ staggerFrom="first"
+ transition={{ type: "spring", damping: 25, stiffness: 160 }}
+ >
+ Stay hungry, stay foolish
+ </Text3DFlip>
+ )
+}
+
+
+===== EXAMPLE: text-3d-flip-demo-2 =====
+Title: Text 3D Flip Demo 2
+
+--- file: example/text-3d-flip-demo-2.tsx ---
+import Text3DFlip from "@/registry/magicui/text-3d-flip"
+
+export default function Text3DFlipDemo2() {
+ return (
+ <Text3DFlip
+ className="bg-background font-serif text-2xl sm:text-5xl md:text-[56px]"
+ textClassName="bg-background text-foreground"
+ flipTextClassName="bg-background text-foreground"
+ rotateDirection="top"
+ staggerDuration={0.03}
+ staggerFrom="center"
+ >
+ Design for failure
+ </Text3DFlip>
+ )
+}
+
+
+
===== COMPONENT: text-animate =====
Title: Text Animate
Description: A text animation component that animates text using a variety of different animations.
diff --git a/apps/www/public/llms.txt b/apps/www/public/llms.txt
index e304bf1f..ef2ccf07 100644
--- a/apps/www/public/llms.txt
+++ b/apps/www/public/llms.txt
@@ -71,6 +71,7 @@ This file provides LLM-friendly entry points to documentation and examples.
- [Spinning Text](https://magicui.design/docs/components/spinning-text): The Spinning Text component animates text in a circular motion with customizable speed, direction, color, and transitions for dynamic and engaging effects.
- [Striped Pattern](https://magicui.design/docs/components/striped-pattern): A background striped pattern made with SVGs, fully customizable using Tailwind CSS.
- [Terminal](https://magicui.design/docs/components/terminal): A terminal component
+- [Text 3D Flip](https://magicui.design/docs/components/text-3d-flip): A text effect that flips each letter in 3D with a staggered animation on hover.
- [Text Animate](https://magicui.design/docs/components/text-animate): A text animation component that animates text using a variety of different animations.
- [Text Reveal](https://magicui.design/docs/components/text-reveal): Fade in text as you scroll down the page.
- [Tweet Card](https://magicui.design/docs/components/tweet-card): A card that displays a tweet with the author's name, handle, and profile picture.
@@ -230,6 +231,8 @@ This file provides LLM-friendly entry points to documentation and examples.
- [backlight-video-demo](https://github.com/magicuidesign/magicui/blob/main/example/backlight-video-demo.tsx): Example usage
- [backlight-image-demo](https://github.com/magicuidesign/magicui/blob/main/example/backlight-image-demo.tsx): Example usage
- [backlight-svg-demo](https://github.com/magicuidesign/magicui/blob/main/example/backlight-svg-demo.tsx): Example usage
+- [Text 3D Flip Demo](https://github.com/magicuidesign/magicui/blob/main/example/text-3d-flip-demo.tsx): Example usage
+- [Text 3D Flip Demo 2](https://github.com/magicuidesign/magicui/blob/main/example/text-3d-flip-demo-2.tsx): Example usage
## Optional
diff --git a/apps/www/public/r/registry.json b/apps/www/public/r/registry.json
index 34ffc41b..170e85d8 100644
--- a/apps/www/public/r/registry.json
+++ b/apps/www/public/r/registry.json
@@ -1292,6 +1292,21 @@
}
]
},
+ {
+ "name": "text-3d-flip",
+ "type": "registry:ui",
+ "title": "Text 3D Flip",
+ "description": "A text effect that flips each letter in 3D with a staggered animation on hover.",
+ "dependencies": [
+ "motion"
+ ],
+ "files": [
+ {
+ "path": "registry/magicui/text-3d-flip.tsx",
+ "type": "registry:ui"
+ }
+ ]
+ },
{
"name": "magic-card-demo",
"type": "registry:example",
@@ -3584,6 +3599,36 @@
}
]
},
+ {
+ "name": "text-3d-flip-demo",
+ "type": "registry:example",
+ "title": "Text 3D Flip Demo",
+ "description": "Example showing a 3D text animation that rotates each letter on hover.",
+ "registryDependencies": [
+ "@magicui/text-3d-flip"
+ ],
+ "files": [
+ {
+ "path": "registry/example/text-3d-flip-demo.tsx",
+ "type": "registry:example"
+ }
+ ]
+ },
+ {
+ "name": "text-3d-flip-demo-2",
+ "type": "registry:example",
+ "title": "Text 3D Flip Demo 2",
+ "description": "Example showing a 3D text flip with stagger from center.",
+ "registryDependencies": [
+ "@magicui/text-3d-flip"
+ ],
+ "files": [
+ {
+ "path": "registry/example/text-3d-flip-demo-2.tsx",
+ "type": "registry:example"
+ }
+ ]
+ },
{
"name": "utils",
"type": "registry:lib",
diff --git a/apps/www/public/r/text-3d-flip-demo-2.json b/apps/www/public/r/text-3d-flip-demo-2.json
new file mode 100644
index 00000000..ddd24525
--- /dev/null
+++ b/apps/www/public/r/text-3d-flip-demo-2.json
@@ -0,0 +1,17 @@
+{
+ "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+ "name": "text-3d-flip-demo-2",
+ "type": "registry:example",
+ "title": "Text 3D Flip Demo 2",
+ "description": "Example showing a 3D text flip with stagger from center.",
+ "registryDependencies": [
+ "@magicui/text-3d-flip"
+ ],
+ "files": [
+ {
+ "path": "registry/example/text-3d-flip-demo-2.tsx",
+ "content": "import Text3DFlip from \"@/registry/magicui/text-3d-flip\"\n\nexport default function Text3DFlipDemo2() {\n return (\n <Text3DFlip\n className=\"bg-background font-serif text-2xl sm:text-5xl md:text-[56px]\"\n textClassName=\"bg-background text-foreground\"\n flipTextClassName=\"bg-background text-foreground\"\n rotateDirection=\"top\"\n staggerDuration={0.03}\n staggerFrom=\"center\"\n >\n Design for failure\n </Text3DFlip>\n )\n}\n",
+ "type": "registry:example"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/apps/www/public/r/text-3d-flip-demo.json b/apps/www/public/r/text-3d-flip-demo.json
new file mode 100644
index 00000000..6f1cff99
--- /dev/null
+++ b/apps/www/public/r/text-3d-flip-demo.json
@@ -0,0 +1,17 @@
+{
+ "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+ "name": "text-3d-flip-demo",
+ "type": "registry:example",
+ "title": "Text 3D Flip Demo",
+ "description": "Example showing a 3D text animation that rotates each letter on hover.",
+ "registryDependencies": [
+ "@magicui/text-3d-flip"
+ ],
+ "files": [
+ {
+ "path": "registry/example/text-3d-flip-demo.tsx",
+ "content": "import Text3DFlip from \"@/registry/magicui/text-3d-flip\"\n\nexport default function Text3DFlipDemo() {\n return (\n <Text3DFlip\n className=\"bg-background font-serif text-2xl sm:text-5xl md:text-[56px]\"\n textClassName=\"bg-background text-foreground\"\n flipTextClassName=\"bg-background text-foreground\"\n rotateDirection=\"top\"\n staggerDuration={0.03}\n staggerFrom=\"first\"\n transition={{ type: \"spring\", damping: 25, stiffness: 160 }}\n >\n Stay hungry, stay foolish\n </Text3DFlip>\n )\n}\n",
+ "type": "registry:example"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/apps/www/public/r/text-3d-flip.json b/apps/www/public/r/text-3d-flip.json
new file mode 100644
index 00000000..02a52de1
--- /dev/null
+++ b/apps/www/public/r/text-3d-flip.json
@@ -0,0 +1,17 @@
+{
+ "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+ "name": "text-3d-flip",
+ "type": "registry:ui",
+ "title": "Text 3D Flip",
+ "description": "A text effect that flips each letter in 3D with a staggered animation on hover.",
+ "dependencies": [
+ "motion"
+ ],
+ "files": [
+ {
+ "path": "registry/magicui/text-3d-flip.tsx",
+ "content": "\"use client\"\n\nimport React, {\n memo,\n useCallback,\n useEffect,\n useMemo,\n useRef,\n type ElementType,\n} from \"react\"\nimport {\n useAnimate,\n type AnimationOptions,\n type ValueAnimationTransition,\n} from \"motion/react\"\n\nimport { cn } from \"@/lib/utils\"\n\nconst HAS_SEGMENTER = typeof Intl !== \"undefined\" && \"Segmenter\" in Intl\n\nconst splitIntoCharacters = (text: string): string[] => {\n if (HAS_SEGMENTER) {\n const segmenter = new Intl.Segmenter(\"en\", { granularity: \"grapheme\" })\n return Array.from(segmenter.segment(text), ({ segment }) => segment)\n }\n return Array.from(text)\n}\n\nconst extractTextFromChildren = (children: React.ReactNode): string => {\n if (children == null) return \"\"\n if (typeof children === \"string\") return children\n if (typeof children === \"number\") return String(children)\n\n if (Array.isArray(children)) {\n return children.map(extractTextFromChildren).join(\"\")\n }\n\n if (React.isValidElement(children)) {\n const props = children.props as Record<string, unknown>\n const childText = props.children as React.ReactNode\n if (childText != null) {\n return extractTextFromChildren(childText)\n }\n }\n\n return \"\"\n}\n\nconst ROTATION_MAP = {\n top: \"rotateX(90deg)\",\n right: \"rotateY(90deg)\",\n bottom: \"rotateX(-90deg)\",\n left: \"rotateY(-90deg)\",\n} as const\n\nconst DEFAULT_TRANSITION: ValueAnimationTransition = {\n type: \"spring\",\n damping: 30,\n stiffness: 300,\n}\n\ninterface Text3DFlipProps {\n children: React.ReactNode\n as?: ElementType\n className?: string\n textClassName?: string\n flipTextClassName?: string\n staggerDuration?: number\n staggerFrom?: \"first\" | \"last\" | \"center\" | number | \"random\"\n transition?: ValueAnimationTransition | AnimationOptions\n rotateDirection?: \"top\" | \"right\" | \"bottom\" | \"left\"\n}\n\nconst Text3DFlip = ({\n children,\n as: ElementTag = \"p\",\n className,\n textClassName,\n flipTextClassName,\n staggerDuration = 0.05,\n staggerFrom = \"first\",\n transition = DEFAULT_TRANSITION,\n rotateDirection = \"right\",\n ...props\n}: Text3DFlipProps) => {\n const isAnimatingRef = useRef(false)\n const isMountedRef = useRef(false)\n const [scope, animate] = useAnimate()\n\n const rotationTransform = ROTATION_MAP[rotateDirection]\n\n useEffect(() => {\n isMountedRef.current = true\n\n return () => {\n isMountedRef.current = false\n isAnimatingRef.current = false\n }\n }, [])\n\n const text = useMemo(() => {\n try {\n return extractTextFromChildren(children)\n } catch {\n return \"\"\n }\n }, [children])\n\n const characters = useMemo(() => {\n const words = text.split(\" \")\n return words.map((word, i) => ({\n characters: splitIntoCharacters(word),\n needsSpace: i !== words.length - 1,\n }))\n }, [text])\n\n const charOffsets = useMemo(() => {\n const offsets = [0]\n for (const word of characters) {\n offsets.push(offsets.at(-1)! + word.characters.length)\n }\n return offsets\n }, [characters])\n\n const getStaggerDelay = useCallback(\n (index: number, totalChars: number) => {\n if (staggerFrom === \"first\") return index * staggerDuration\n if (staggerFrom === \"last\")\n return (totalChars - 1 - index) * staggerDuration\n if (staggerFrom === \"center\") {\n const center = Math.floor(totalChars / 2)\n return Math.abs(center - index) * staggerDuration\n }\n if (staggerFrom === \"random\") {\n const randomIndex = Math.floor(Math.random() * totalChars)\n return Math.abs(randomIndex - index) * staggerDuration\n }\n return Math.abs(staggerFrom - index) * staggerDuration\n },\n [staggerFrom, staggerDuration]\n )\n\n const handleHoverStart = useCallback(async () => {\n if (isAnimatingRef.current) return\n isAnimatingRef.current = true\n\n try {\n const totalChars = characters.reduce(\n (sum, word) => sum + word.characters.length,\n 0\n )\n\n const delays = Array.from({ length: totalChars }, (_, i) =>\n getStaggerDelay(i, totalChars)\n )\n\n await animate(\n \".text-3d-flip-char\",\n { transform: rotationTransform },\n {\n ...transition,\n delay: (i: number) => delays[i],\n }\n )\n\n if (!isMountedRef.current) return\n\n await animate(\n \".text-3d-flip-char\",\n { transform: \"rotateX(0deg) rotateY(0deg)\" },\n { duration: 0 }\n )\n } finally {\n if (isMountedRef.current) {\n isAnimatingRef.current = false\n }\n }\n }, [characters, transition, getStaggerDelay, rotationTransform, animate])\n\n return (\n <ElementTag\n className={cn(\"relative flex flex-wrap\", className)}\n onMouseEnter={handleHoverStart}\n ref={scope}\n {...props}\n >\n <span className=\"sr-only\">{text}</span>\n\n {characters.map((wordObj, wordIndex) => (\n <span key={wordIndex} className=\"inline-flex\">\n {wordObj.characters.map((char, charIndex) => (\n <CharBox\n key={charOffsets[wordIndex] + charIndex}\n char={char}\n textClassName={textClassName}\n flipTextClassName={flipTextClassName}\n rotateDirection={rotateDirection}\n />\n ))}\n {wordObj.needsSpace && <span className=\"whitespace-pre\"> </span>}\n </span>\n ))}\n </ElementTag>\n )\n}\n\ninterface CharBoxProps {\n char: string\n textClassName?: string\n flipTextClassName?: string\n rotateDirection: \"top\" | \"right\" | \"bottom\" | \"left\"\n}\n\nconst SECOND_FACE_TRANSFORMS = {\n top: \"rotateX(-90deg) translateZ(0.5lh)\",\n right:\n \"rotateY(90deg) translateX(50%) rotateY(-90deg) translateX(-50%) rotateY(-90deg) translateX(50%)\",\n bottom: \"rotateX(90deg) translateZ(0.5lh)\",\n left: \"rotateY(90deg) translateX(50%) rotateY(-90deg) translateX(50%) rotateY(-90deg) translateX(50%)\",\n} as const\n\nconst FRONT_FACE_TRANSFORMS = {\n top: \"translateZ(0.5lh)\",\n bottom: \"translateZ(0.5lh)\",\n left: \"rotateY(90deg) translateX(50%) rotateY(-90deg)\",\n right: \"rotateY(-90deg) translateX(50%) rotateY(90deg)\",\n} as const\n\nconst CONTAINER_TRANSFORMS = {\n top: \"translateZ(-0.5lh)\",\n bottom: \"translateZ(-0.5lh)\",\n left: \"rotateY(90deg) translateX(50%) rotateY(-90deg)\",\n right: \"rotateY(90deg) translateX(50%) rotateY(-90deg)\",\n} as const\n\nconst CharBox = memo(\n ({\n char,\n textClassName,\n flipTextClassName,\n rotateDirection,\n }: CharBoxProps) => (\n <span\n className=\"text-3d-flip-char inline transform-3d\"\n style={{ transform: CONTAINER_TRANSFORMS[rotateDirection] }}\n >\n <span\n className={cn(\"relative h-[1lh] backface-hidden\", textClassName)}\n style={{ transform: FRONT_FACE_TRANSFORMS[rotateDirection] }}\n >\n {char}\n </span>\n <span\n className={cn(\n \"absolute top-0 left-0 h-[1lh] backface-hidden\",\n flipTextClassName\n )}\n style={{ transform: SECOND_FACE_TRANSFORMS[rotateDirection] }}\n >\n {char}\n </span>\n </span>\n )\n)\n\nCharBox.displayName = \"CharBox\"\nText3DFlip.displayName = \"Text3DFlip\"\n\nexport default Text3DFlip\n",
+ "type": "registry:ui"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/apps/www/public/registry.json b/apps/www/public/registry.json
index 34ffc41b..170e85d8 100644
--- a/apps/www/public/registry.json
+++ b/apps/www/public/registry.json
@@ -1292,6 +1292,21 @@
}
]
},
+ {
+ "name": "text-3d-flip",
+ "type": "registry:ui",
+ "title": "Text 3D Flip",
+ "description": "A text effect that flips each letter in 3D with a staggered animation on hover.",
+ "dependencies": [
+ "motion"
+ ],
+ "files": [
+ {
+ "path": "registry/magicui/text-3d-flip.tsx",
+ "type": "registry:ui"
+ }
+ ]
+ },
{
"name": "magic-card-demo",
"type": "registry:example",
@@ -3584,6 +3599,36 @@
}
]
},
+ {
+ "name": "text-3d-flip-demo",
+ "type": "registry:example",
+ "title": "Text 3D Flip Demo",
+ "description": "Example showing a 3D text animation that rotates each letter on hover.",
+ "registryDependencies": [
+ "@magicui/text-3d-flip"
+ ],
+ "files": [
+ {
+ "path": "registry/example/text-3d-flip-demo.tsx",
+ "type": "registry:example"
+ }
+ ]
+ },
+ {
+ "name": "text-3d-flip-demo-2",
+ "type": "registry:example",
+ "title": "Text 3D Flip Demo 2",
+ "description": "Example showing a 3D text flip with stagger from center.",
+ "registryDependencies": [
+ "@magicui/text-3d-flip"
+ ],
+ "files": [
+ {
+ "path": "registry/example/text-3d-flip-demo-2.tsx",
+ "type": "registry:example"
+ }
+ ]
+ },
{
"name": "utils",
"type": "registry:lib",
diff --git a/apps/www/registry.json b/apps/www/registry.json
index 34ffc41b..170e85d8 100644
--- a/apps/www/registry.json
+++ b/apps/www/registry.json
@@ -1292,6 +1292,21 @@
}
]
},
+ {
+ "name": "text-3d-flip",
+ "type": "registry:ui",
+ "title": "Text 3D Flip",
+ "description": "A text effect that flips each letter in 3D with a staggered animation on hover.",
+ "dependencies": [
+ "motion"
+ ],
+ "files": [
+ {
+ "path": "registry/magicui/text-3d-flip.tsx",
+ "type": "registry:ui"
+ }
+ ]
+ },
{
"name": "magic-card-demo",
"type": "registry:example",
@@ -3584,6 +3599,36 @@
}
]
},
+ {
+ "name": "text-3d-flip-demo",
+ "type": "registry:example",
+ "title": "Text 3D Flip Demo",
+ "description": "Example showing a 3D text animation that rotates each letter on hover.",
+ "registryDependencies": [
+ "@magicui/text-3d-flip"
+ ],
+ "files": [
+ {
+ "path": "registry/example/text-3d-flip-demo.tsx",
+ "type": "registry:example"
+ }
+ ]
+ },
+ {
+ "name": "text-3d-flip-demo-2",
+ "type": "registry:example",
+ "title": "Text 3D Flip Demo 2",
+ "description": "Example showing a 3D text flip with stagger from center.",
+ "registryDependencies": [
+ "@magicui/text-3d-flip"
+ ],
+ "files": [
+ {
+ "path": "registry/example/text-3d-flip-demo-2.tsx",
+ "type": "registry:example"
+ }
+ ]
+ },
{
"name": "utils",
"type": "registry:lib",
diff --git a/apps/www/registry/__index__.tsx b/apps/www/registry/__index__.tsx
index 20ed79ef..31b61da3 100644
--- a/apps/www/registry/__index__.tsx
+++ b/apps/www/registry/__index__.tsx
@@ -1239,6 +1239,23 @@ export const Index: Record<string, any> = {
}),
meta: undefined,
},
+ "text-3d-flip": {
+ name: "text-3d-flip",
+ description: "A text effect that flips each letter in 3D with a staggered animation on hover.",
+ type: "registry:ui",
+ registryDependencies: undefined,
+ files: [{
+ path: "registry/magicui/text-3d-flip.tsx",
+ type: "registry:ui",
+ target: ""
+ }],
+ component: React.lazy(async () => {
+ const mod = await import("@/registry/magicui/text-3d-flip.tsx")
+ const exportName = Object.keys(mod).find(key => typeof mod[key] === 'function' || typeof mod[key] === 'object') ?? item.name
+ return { default: mod.default ?? mod[exportName] }
+ }),
+ meta: undefined,
+ },
"magic-card-demo": {
name: "magic-card-demo",
description: "Example showing a spotlight effect that follows your mouse cursor and highlights borders on hover.",
@@ -3776,6 +3793,40 @@ export const Index: Record<string, any> = {
}),
meta: undefined,
},
+ "text-3d-flip-demo": {
+ name: "text-3d-flip-demo",
+ description: "Example showing a 3D text animation that rotates each letter on hover.",
+ type: "registry:example",
+ registryDependencies: ["@magicui/text-3d-flip"],
+ files: [{
+ path: "registry/example/text-3d-flip-demo.tsx",
+ type: "registry:example",
+ target: ""
+ }],
+ component: React.lazy(async () => {
+ const mod = await import("@/registry/example/text-3d-flip-demo.tsx")
+ const exportName = Object.keys(mod).find(key => typeof mod[key] === 'function' || typeof mod[key] === 'object') ?? item.name
+ return { default: mod.default ?? mod[exportName] }
+ }),
+ meta: undefined,
+ },
+ "text-3d-flip-demo-2": {
+ name: "text-3d-flip-demo-2",
+ description: "Example showing a 3D text flip with stagger from center.",
+ type: "registry:example",
+ registryDependencies: ["@magicui/text-3d-flip"],
+ files: [{
+ path: "registry/example/text-3d-flip-demo-2.tsx",
+ type: "registry:example",
+ target: ""
+ }],
+ component: React.lazy(async () => {
+ const mod = await import("@/registry/example/text-3d-flip-demo-2.tsx")
+ const exportName = Object.keys(mod).find(key => typeof mod[key] === 'function' || typeof mod[key] === 'object') ?? item.name
+ return { default: mod.default ?? mod[exportName] }
+ }),
+ meta: undefined,
+ },
"utils": {
name: "utils",
description: "",
diff --git a/apps/www/registry/example/text-3d-flip-demo-2.tsx b/apps/www/registry/example/text-3d-flip-demo-2.tsx
new file mode 100644
index 00000000..826adf1a
--- /dev/null
+++ b/apps/www/registry/example/text-3d-flip-demo-2.tsx
@@ -0,0 +1,16 @@
+import Text3DFlip from "@/registry/magicui/text-3d-flip"
+
+export default function Text3DFlipDemo2() {
+ return (
+ <Text3DFlip
+ className="bg-background font-serif text-2xl sm:text-5xl md:text-[56px]"
+ textClassName="bg-background text-foreground"
+ flipTextClassName="bg-background text-foreground"
+ rotateDirection="top"
+ staggerDuration={0.03}
+ staggerFrom="center"
+ >
+ Design for failure
+ </Text3DFlip>
+ )
+}
diff --git a/apps/www/registry/example/text-3d-flip-demo.tsx b/apps/www/registry/example/text-3d-flip-demo.tsx
new file mode 100644
index 00000000..2e0e8a2b
--- /dev/null
+++ b/apps/www/registry/example/text-3d-flip-demo.tsx
@@ -0,0 +1,17 @@
+import Text3DFlip from "@/registry/magicui/text-3d-flip"
+
+export default function Text3DFlipDemo() {
+ return (
+ <Text3DFlip
+ className="bg-background font-serif text-2xl sm:text-5xl md:text-[56px]"
+ textClassName="bg-background text-foreground"
+ flipTextClassName="bg-background text-foreground"
+ rotateDirection="top"
+ staggerDuration={0.03}
+ staggerFrom="first"
+ transition={{ type: "spring", damping: 25, stiffness: 160 }}
+ >
+ Stay hungry, stay foolish
+ </Text3DFlip>
+ )
+}
diff --git a/apps/www/registry/magicui/text-3d-flip.tsx b/apps/www/registry/magicui/text-3d-flip.tsx
new file mode 100644
index 00000000..9f20a6e4
--- /dev/null
+++ b/apps/www/registry/magicui/text-3d-flip.tsx
@@ -0,0 +1,269 @@
+"use client"
+
+import React, {
+ memo,
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ type ElementType,
+} from "react"
+import {
+ useAnimate,
+ type AnimationOptions,
+ type ValueAnimationTransition,
+} from "motion/react"
+
+import { cn } from "@/lib/utils"
+
+const HAS_SEGMENTER = typeof Intl !== "undefined" && "Segmenter" in Intl
+
+const splitIntoCharacters = (text: string): string[] => {
+ if (HAS_SEGMENTER) {
+ const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" })
+ return Array.from(segmenter.segment(text), ({ segment }) => segment)
+ }
+ return Array.from(text)
+}
+
+const extractTextFromChildren = (children: React.ReactNode): string => {
+ if (children == null) return ""
+ if (typeof children === "string") return children
+ if (typeof children === "number") return String(children)
+
+ if (Array.isArray(children)) {
+ return children.map(extractTextFromChildren).join("")
+ }
+
+ if (React.isValidElement(children)) {
+ const props = children.props as Record<string, unknown>
+ const childText = props.children as React.ReactNode
+ if (childText != null) {
+ return extractTextFromChildren(childText)
+ }
+ }
+
+ return ""
+}
+
+const ROTATION_MAP = {
+ top: "rotateX(90deg)",
+ right: "rotateY(90deg)",
+ bottom: "rotateX(-90deg)",
+ left: "rotateY(-90deg)",
+} as const
+
+const DEFAULT_TRANSITION: ValueAnimationTransition = {
+ type: "spring",
+ damping: 30,
+ stiffness: 300,
+}
+
+interface Text3DFlipProps {
+ children: React.ReactNode
+ as?: ElementType
+ className?: string
+ textClassName?: string
+ flipTextClassName?: string
+ staggerDuration?: number
+ staggerFrom?: "first" | "last" | "center" | number | "random"
+ transition?: ValueAnimationTransition | AnimationOptions
+ rotateDirection?: "top" | "right" | "bottom" | "left"
+}
+
+const Text3DFlip = ({
+ children,
+ as: ElementTag = "p",
+ className,
+ textClassName,
+ flipTextClassName,
+ staggerDuration = 0.05,
+ staggerFrom = "first",
+ transition = DEFAULT_TRANSITION,
+ rotateDirection = "right",
+ ...props
+}: Text3DFlipProps) => {
+ const isAnimatingRef = useRef(false)
+ const isMountedRef = useRef(false)
+ const [scope, animate] = useAnimate()
+
+ const rotationTransform = ROTATION_MAP[rotateDirection]
+
+ useEffect(() => {
+ isMountedRef.current = true
+
+ return () => {
+ isMountedRef.current = false
+ isAnimatingRef.current = false
+ }
+ }, [])
+
+ const text = useMemo(() => {
+ try {
+ return extractTextFromChildren(children)
+ } catch {
+ return ""
+ }
+ }, [children])
+
+ const characters = useMemo(() => {
+ const words = text.split(" ")
+ return words.map((word, i) => ({
+ characters: splitIntoCharacters(word),
+ needsSpace: i !== words.length - 1,
+ }))
+ }, [text])
+
+ const charOffsets = useMemo(() => {
+ const offsets = [0]
+ for (const word of characters) {
+ offsets.push(offsets.at(-1)! + word.characters.length)
+ }
+ return offsets
+ }, [characters])
+
+ const getStaggerDelay = useCallback(
+ (index: number, totalChars: number) => {
+ if (staggerFrom === "first") return index * staggerDuration
+ if (staggerFrom === "last")
+ return (totalChars - 1 - index) * staggerDuration
+ if (staggerFrom === "center") {
+ const center = Math.floor(totalChars / 2)
+ return Math.abs(center - index) * staggerDuration
+ }
+ if (staggerFrom === "random") {
+ const randomIndex = Math.floor(Math.random() * totalChars)
+ return Math.abs(randomIndex - index) * staggerDuration
+ }
+ return Math.abs(staggerFrom - index) * staggerDuration
+ },
+ [staggerFrom, staggerDuration]
+ )
+
+ const handleHoverStart = useCallback(async () => {
+ if (isAnimatingRef.current) return
+ isAnimatingRef.current = true
+
+ try {
+ const totalChars = characters.reduce(
+ (sum, word) => sum + word.characters.length,
+ 0
+ )
+
+ const delays = Array.from({ length: totalChars }, (_, i) =>
+ getStaggerDelay(i, totalChars)
+ )
+
+ await animate(
+ ".text-3d-flip-char",
+ { transform: rotationTransform },
+ {
+ ...transition,
+ delay: (i: number) => delays[i],
+ }
+ )
+
+ if (!isMountedRef.current) return
+
+ await animate(
+ ".text-3d-flip-char",
+ { transform: "rotateX(0deg) rotateY(0deg)" },
+ { duration: 0 }
+ )
+ } finally {
+ if (isMountedRef.current) {
+ isAnimatingRef.current = false
+ }
+ }
+ }, [characters, transition, getStaggerDelay, rotationTransform, animate])
+
+ return (
+ <ElementTag
+ className={cn("relative flex flex-wrap", className)}
+ onMouseEnter={handleHoverStart}
+ ref={scope}
+ {...props}
+ >
+ <span className="sr-only">{text}</span>
+
+ {characters.map((wordObj, wordIndex) => (
+ <span key={wordIndex} className="inline-flex">
+ {wordObj.characters.map((char, charIndex) => (
+ <CharBox
+ key={charOffsets[wordIndex] + charIndex}
+ char={char}
+ textClassName={textClassName}
+ flipTextClassName={flipTextClassName}
+ rotateDirection={rotateDirection}
+ />
+ ))}
+ {wordObj.needsSpace && <span className="whitespace-pre"> </span>}
+ </span>
+ ))}
+ </ElementTag>
+ )
+}
+
+interface CharBoxProps {
+ char: string
+ textClassName?: string
+ flipTextClassName?: string
+ rotateDirection: "top" | "right" | "bottom" | "left"
+}
+
+const SECOND_FACE_TRANSFORMS = {
+ top: "rotateX(-90deg) translateZ(0.5lh)",
+ right:
+ "rotateY(90deg) translateX(50%) rotateY(-90deg) translateX(-50%) rotateY(-90deg) translateX(50%)",
+ bottom: "rotateX(90deg) translateZ(0.5lh)",
+ left: "rotateY(90deg) translateX(50%) rotateY(-90deg) translateX(50%) rotateY(-90deg) translateX(50%)",
+} as const
+
+const FRONT_FACE_TRANSFORMS = {
+ top: "translateZ(0.5lh)",
+ bottom: "translateZ(0.5lh)",
+ left: "rotateY(90deg) translateX(50%) rotateY(-90deg)",
+ right: "rotateY(-90deg) translateX(50%) rotateY(90deg)",
+} as const
+
+const CONTAINER_TRANSFORMS = {
+ top: "translateZ(-0.5lh)",
+ bottom: "translateZ(-0.5lh)",
+ left: "rotateY(90deg) translateX(50%) rotateY(-90deg)",
+ right: "rotateY(90deg) translateX(50%) rotateY(-90deg)",
+} as const
+
+const CharBox = memo(
+ ({
+ char,
+ textClassName,
+ flipTextClassName,
+ rotateDirection,
+ }: CharBoxProps) => (
+ <span
+ className="text-3d-flip-char inline transform-3d"
+ style={{ transform: CONTAINER_TRANSFORMS[rotateDirection] }}
+ >
+ <span
+ className={cn("relative h-[1lh] backface-hidden", textClassName)}
+ style={{ transform: FRONT_FACE_TRANSFORMS[rotateDirection] }}
+ >
+ {char}
+ </span>
+ <span
+ className={cn(
+ "absolute top-0 left-0 h-[1lh] backface-hidden",
+ flipTextClassName
+ )}
+ style={{ transform: SECOND_FACE_TRANSFORMS[rotateDirection] }}
+ >
+ {char}
+ </span>
+ </span>
+ )
+)
+
+CharBox.displayName = "CharBox"
+Text3DFlip.displayName = "Text3DFlip"
+
+export default Text3DFlip
diff --git a/apps/www/registry/registry-examples.ts b/apps/www/registry/registry-examples.ts
index 98613dfd..8b61c39f 100644
--- a/apps/www/registry/registry-examples.ts
+++ b/apps/www/registry/registry-examples.ts
@@ -1983,4 +1983,31 @@ export const examples: Registry["items"] = [
},
],
},
+ {
+ name: "text-3d-flip-demo",
+ type: "registry:example",
+ title: "Text 3D Flip Demo",
+ description:
+ "Example showing a 3D text animation that rotates each letter on hover.",
+ registryDependencies: ["@magicui/text-3d-flip"],
+ files: [
+ {
+ path: "example/text-3d-flip-demo.tsx",
+ type: "registry:example",
+ },
+ ],
+ },
+ {
+ name: "text-3d-flip-demo-2",
+ type: "registry:example",
+ title: "Text 3D Flip Demo 2",
+ description: "Example showing a 3D text flip with stagger from center.",
+ registryDependencies: ["@magicui/text-3d-flip"],
+ files: [
+ {
+ path: "example/text-3d-flip-demo-2.tsx",
+ type: "registry:example",
+ },
+ ],
+ },
]
diff --git a/apps/www/registry/registry-ui.ts b/apps/www/registry/registry-ui.ts
index 7cd570a0..e130dd65 100644
--- a/apps/www/registry/registry-ui.ts
+++ b/apps/www/registry/registry-ui.ts
@@ -1243,4 +1243,18 @@ export const ui: Registry["items"] = [
},
],
},
+ {
+ name: "text-3d-flip",
+ type: "registry:ui",
+ title: "Text 3D Flip",
+ description:
+ "A text effect that flips each letter in 3D with a staggered animation on hover.",
+ dependencies: ["motion"],
+ files: [
+ {
+ path: "magicui/text-3d-flip.tsx",
+ type: "registry:ui",
+ },
+ ],
+ },
]