react-quiz-component

JSON-powered React quizzes with scoring, timers, feedback, images, multiple-choice answers, and customizable results. Use the ready-made Quiz component or build your own UI with headless hooks.

Installation

npm install react-quiz-component

React and React DOM 18 or 19 are required as peer dependencies.

Quick start

'use client'; // Required in a Next.js App Router client boundary.
import Quiz, { type Quiz as QuizData } from 'react-quiz-component';

const quiz: QuizData = {
  quizTitle: 'Your first quiz',
  questions: [
    {
      question: 'Which hook stores local state?',
      questionType: 'text',
      answerSelectionType: 'single',
      answers: ['useState', 'useEffect'],
      correctAnswer: '1',
      point: 10,
    },
  ],
};

export default function App() {
  return <Quiz quiz={quiz} showInstantFeedback enableProgressBar />;
}

Headless APIs are available as named exports: useQuiz, QuizProvider, and useQuizContext. See the headless guide.

Documentation

Read the documentation for guides and the full API reference, or explore the interactive examples with runnable previews and source code.

Development

pnpm install
pnpm dev               # Builds the local library, then starts docs on localhost:3000
pnpm typecheck
pnpm test
pnpm build
pnpm test:package
pnpm test:react        # Installs packed consumers to verify React 18 and 19 (requires registry access)
pnpm build:docs        # Static site in docs/out
pnpm typecheck:docs
pnpm test:docs         # Browser checks against the static export

Install the test browser once with pnpm --filter @react-quiz/docs exec playwright install chromium. After changing library source, rebuild with pnpm build (or restart pnpm dev) so the docs use the updated package. Documentation and demo source live in docs.

Submit contributions to develop.

License

MIT