測驗卡｜免費 React 元件

單選／複選測驗卡 React 元件：選答後正確選項描出勾、錯誤選項抖動、解說展開，下一題方向性滑入，含進度、逐位滾動的分數與結束頁。

給課程、活動頁或產品導覽用的測驗卡。單選題點一下就判定；複選題勾好後按「確認答案」。判定後正確選項轉綠框、右側圓圈內的勾一筆描出，選錯的選項轉紅框並水平抖動，其他選項淡出，解說區以高度展開。按「下一題」或 Enter，目前題目往左滑出、新題從右滑入；頂部有進度條與逐位滾動的分數，最後一題結束後進入結束頁，顯示總分、評語與逐題對錯，可點任一題回看或「再玩一次」。

把這個效果裝進你的專案

在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。

npx webberui@latest add quiz-card

還沒有專案，或安裝遇到問題？看快速開始 →

Playground

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

作答模式mode

動畫秒數duration

0.35

允許回上一題allowBack

打亂選項shuffleOptions

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

編輯中的呼叫預設屬性

<QuizCard/>

    </div>
  );
}

完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。

安裝

npx webberui@latest add https://webberui.com/r/quiz-card.json

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

使用

import { QuizCard } from "@/components/ui/quiz-card";

<QuizCard
  questions={[
    {
      q: "台灣最高的山是？",
      options: ["雪山", "玉山", "合歡山", "阿里山"],
      answer: 1,
      explanation: "玉山主峰海拔約 3,952 公尺。",
    },
    {
      q: "下列哪些是台灣的離島？（複選）",
      options: ["澎湖", "金門", "蘭嶼", "沖繩"],
      answer: [0, 1, 2],
    },
  ]}
  allowBack
  onAnswer={(index, correct) => console.log(index, correct)}
  onComplete={(score, total) => console.log(`${score} / ${total}`)}
/>

Props

Prop	型別	預設值	說明
`questions`	`QuizQuestion[]`	—	題目清單
`mode`	`"single" \| "multiple"`	`"single"`	作答模式；`answer` 為陣列的題目一律視為複選
`duration`	`number`	`0.35`	勾描、解說展開與進度條的動畫秒數（同時寫入 `--wb-quiz-duration`）
`shuffleOptions`	`boolean \| number`	`false`	打亂選項順序；傳數字作為確定性 seed（同 seed 每次結果相同，SSR 安全）
`allowBack`	`boolean`	`false`	允許回到上一題（已作答的題目維持鎖定）
`value`	`number`	—	受控的目前題目 index；未提供時由元件內部管理
`defaultValue`	`number`	`0`	非受控模式的起始題目 index
`onChange`	`(index: number) => void`	—	目前題目變動時回呼
`onAnswer`	`(index: number, correct: boolean) => void`	—	每題判定後回呼，參數為題目 index 與是否答對
`onComplete`	`(score: number, total: number) => void`	—	進入結束頁時回呼，參數為答對題數與總題數
`labels`	`QuizCardLabels`	—	介面文字，未提供的欄位使用繁中預設值
`className`	`string`	—	透傳到最外層容器

QuizQuestion

欄位	型別	預設值	說明
`id`	`string`	—	題目識別碼；提供時作為打亂選項的 seed 來源與 React key
`q`	`ReactNode`	—	題目內容
`options`	`ReactNode[]`	—	選項內容（依原始順序；`answer` 以這個順序的 index 表示）
`answer`	`number \| number[]`	—	正確答案的 index；傳陣列代表複選題
`explanation`	`ReactNode`	—	作答後展開的解說

QuizCardLabels

欄位	型別	預設值	說明
`progress`	`(current: number, total: number) => string`	`第 2 / 5 題` 格式	進度文字
`score`	`string`	`"分數"`	分數標籤
`confirm`	`string`	`"確認答案"`	複選題的確認按鈕
`next` / `prev`	`string`	`"下一題"` / `"上一題"`	換題按鈕
`finish`	`string`	`"看結果"`	最後一題作答後前往結束頁
`restart`	`string`	`"再玩一次"`	結束頁重新開始按鈕
`correct`	`string`	`"答對了"`	答對時朗讀的文字
`wrong`	`(answer: string) => string`	`答錯了，正確答案是 B` 格式	答錯時朗讀的文字
`verdicts`	`[string, string, string]`	`["太厲害了", "不錯喔", "再接再厲"]`	依答對比例（80% 以上、50% 以上、其餘）的評語

另有 quiz、multipleHint、keyHint、backToResult、correctTag、wrongTag、resultTitle、review、answeredCorrect、answeredWrong、unanswered 可覆寫，完整說明見原始碼 JSDoc。

細節

顏色可用 CSS 變數覆寫：--wb-quiz-correct（預設 emerald-500）、--wb-quiz-wrong（預設 red-500）；--wb-quiz-duration 由 duration 寫入，控制進度條寬度動畫。
換題以 AnimatePresence mode="wait" 搭配方向：往後題目往左滑出、新題從右滑入（彈簧 stiffness 300、damping 30）；上一題與回看則反向。
分數在本元件內以逐位滾動呈現：每一位數各自從下方捲入，只有變動的那一位會動。
shuffleOptions 用確定性雜湊產生排列，伺服器與瀏覽器渲染結果一致；選項代號 A、B、C 與數字鍵都依「顯示順序」對應。
已作答的題目會鎖定；開啟 allowBack 或從結束頁點選某題時，回看畫面直接顯示當時的作答結果，不重播動畫。

可及性

單選題選項為 role="radiogroup" / role="radio"（roving tabindex），複選題為 role="group" / role="checkbox"，以 aria-checked 表示勾選；方向鍵、Home、End 可在選項間移動
數字鍵 1–9 選擇對應選項，Enter 確認複選或前往下一題；中文等輸入法組字中的按鍵一律忽略
判定結果以 aria-live="assertive" 朗讀「答對了」或「答錯了，正確答案是 B」
正確與錯誤除顏色外，另有勾／叉圖示與「正解」「選錯」文字；結束頁每題附螢幕閱讀器文字
頂部進度條為 role="progressbar"，分數滾動動畫對輔助科技隱藏，改以純文字提供
使用者系統開啟「減少動態效果」時，選錯不抖動、勾直接出現、換題改為淡入淡出

測驗卡

把這個效果裝進你的專案

本頁目錄