Flip Reveal Card

3D 翻面卡片，繞 X／Y 軸翻轉揭示正反兩面內容，支援懸停、點擊與完全受控。

載入預覽⋯

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

觸發方式trigger

翻轉軸axis

透視距離perspective

1000

動畫時長（秒）duration

0.6

<FlipRevealCard />

安裝

npx shadcn@latest add https://webberui.com/r/flip-reveal-card.json

或在 components.json 設定 registries 後，改用 @webberui/flip-reveal-card 安裝。

安裝依賴後，從 registry JSON（/r/flip-reveal-card.json 的 files[0].content）複製 flip-reveal-card.tsx 原始碼到你的 components/ui/ 目錄：

npm install motion clsx tailwind-merge

使用

import {
  FlipRevealCard,
  FlipRevealFront,
  FlipRevealBack,
} from "@/components/ui/flip-reveal-card";

<FlipRevealCard trigger="hover" axis="y" className="h-40 w-64">
  <FlipRevealFront>
    <h3 className="text-base font-semibold">正面</h3>
  </FlipRevealFront>
  <FlipRevealBack>
    <p className="text-sm">背面內容，翻過來才看得到。</p>
  </FlipRevealBack>
</FlipRevealCard>

兩面會自動疊放在同一格，卡片高度取兩面內容較高者；也可直接在 FlipRevealCard 上用 className 指定固定高度（如 h-40）。

受控模式

傳入 flipped 即進入受控模式，搭配 trigger="none" 可完全由外部控制翻面：

const [flipped, setFlipped] = React.useState(false);

<>
  <FlipRevealCard trigger="none" flipped={flipped} className="h-40 w-64">
    <FlipRevealFront>正面</FlipRevealFront>
    <FlipRevealBack>背面</FlipRevealBack>
  </FlipRevealCard>
  <button onClick={() => setFlipped((v) => !v)}>翻面</button>
</>

Props

FlipRevealCard

Prop	型別	預設值	說明
`children`	`React.ReactNode`	—	放入 `FlipRevealFront` 與 `FlipRevealBack`
`trigger`	`"hover" \| "click" \| "none"`	`"hover"`	觸發方式：懸停／聚焦、點擊切換、完全受控
`axis`	`"x" \| "y"`	`"y"`	翻轉軸：`y` 左右翻、`x` 上下翻
`flipped`	`boolean`	—	受控狀態；提供時停用內建狀態
`defaultFlipped`	`boolean`	`false`	非受控模式的初始翻面狀態
`onFlippedChange`	`(flipped: boolean) => void`	—	翻面狀態變更時觸發
`perspective`	`number`	`1000`	3D 透視距離（px），越小立體感越強
`duration`	`number`	`0.6`	翻面動畫時長（秒）
`className`	`string`	—	附加到最外層容器（常用來設定寬高）

同時支援其餘標準 div 屬性（如 aria-label）。

FlipRevealFront / FlipRevealBack

Prop	型別	預設值	說明
`children`	`React.ReactNode`	—	該面的內容
`className`	`string`	—	覆寫預設卡面外觀（邊框、背景、內距等）

兩者皆繼承標準 div 屬性。

細節

兩面以 CSS Grid 疊在同一格，並用 backface-visibility: hidden 隱藏背對觀者的一面；旋轉容器帶 transform-style: preserve-3d，切勿在其上加 overflow-hidden（會攤平 3D）。
卡面本身可自由設定 overflow-hidden 與圓角，因為它只是平面內容層。
axis 切換時，背面會自動改用對應軸向的 180° 預旋轉，正反面始終共面對齊。

可及性

使用者系統開啟「減少動態效果」時，翻面改為瞬間切換（duration 0），不做旋轉動畫，也不改變 DOM 結構。
目前朝背面的一面會被標記 aria-hidden 並加上 inert，因此不會被螢幕報讀，其內的可聚焦元素也不進入 Tab 順序。
trigger="click" 時容器為 role="button"、可聚焦，並支援 Enter／空白鍵切換，aria-pressed 反映當前面向。
trigger="hover" 時容器可聚焦，鍵盤聚焦即翻面（等同懸停），失焦翻回；建議透過 aria-label 為卡片命名。

On this page