react-quiz-component

📙 React Quiz Component

react-quiz-component is a ReactJS component that renders a quiz from a JSON object. It supports text and photo answers, single and multiple answer selection, scoring, timers, shuffling, progress display, custom locale text, and result callbacks.

Features

• JSON-based quiz source
• Quiz landing page with title, synopsis, and number of questions
• Input validation for quiz data
• Text and photo answer choices
• Single-answer and multiple-answer questions
• Question markdown support
• Optional question images
• Per-question explanations and answer messages
• Scoring with total and correct points
• Question segments and selection tags
• Question and answer shuffling
• Instant feedback
• Retry-until-correct mode
• Reveal-answer-on-submit mode
• Previous and next navigation
• Default result page with all, correct, incorrect, and unanswered filters
• Custom result page support
• Quiz completion and per-question callbacks
• Timer support with optional pause and resume
• Optional progress bar

Installation

npm i react-quiz-component

Quick Start

import Quiz from 'react-quiz-component';

const quiz = {
  quizTitle: 'React Quiz Component Demo',
  quizSynopsis: 'A short quiz about React basics.',
  nrOfQuestions: 3,
  progressBarColor: '#9de1f6',
  questions: [
    {
      question: 'Which hook lets a function component store local state?',
      questionType: 'text',
      questionPic: 'https://dummyimage.com/600x240/9de1f6/000000&text=React+Hooks',
      answerSelectionType: 'single',
      answers: ['useMemo', 'useState', 'useEffect', 'useRef'],
      correctAnswer: '2',
      messageForCorrectAnswer: 'Correct. useState stores local component state.',
      messageForIncorrectAnswer: 'Not quite. Look for the hook that stores state.',
      explanation: 'useState returns a state value and a setter function.',
      point: 10,
      segment: 'React Hooks',
    },
    {
      question: 'Select the React rendering methods.',
      questionType: 'text',
      answerSelectionType: 'multiple',
      answers: ['createRoot', 'renderToString', 'setTimeout', 'querySelector'],
      correctAnswer: [1, 2],
      messageForCorrectAnswer: 'Correct. React supports client and server rendering APIs.',
      messageForIncorrectAnswer: 'Incorrect. Select only React rendering APIs.',
      explanation: 'createRoot is used for client rendering. renderToString is used for server rendering.',
      point: 20,
      segment: 'Rendering',
    },
    {
      question: 'Which image shows the React logo?',
      questionType: 'photo',
      answerSelectionType: 'single',
      answers: [
        'https://dummyimage.com/300x180/61dafb/000000&text=React',
        'https://dummyimage.com/300x180/f7df1e/000000&text=JS',
        'https://dummyimage.com/300x180/3178c6/ffffff&text=TS',
      ],
      correctAnswer: '1',
      messageForCorrectAnswer: 'Correct.',
      messageForIncorrectAnswer: 'Incorrect.',
      explanation: 'The React logo is commonly shown with a light blue atom-like mark.',
      point: 10,
      segment: 'Logos',
    },
  ],
};

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

You can also import the quiz source from another file:

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

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

Quiz Fields

Name	Type	Required	Description
quizTitle	string	Y	Title shown on the landing page.
quizSynopsis	string	N	Introductory text shown before the quiz starts.
nrOfQuestions	number	N	Number of questions to use from questions. If omitted, all questions are used.
questions	Question[]	Y	Question definitions.
appLocale	Partial<AppLocale>	N	Locale text overrides.
progressBarColor	string	N	Hex color used by the progress bar. Defaults to #9de1f6.

Question Fields

Name	Type	Required	Description
question	string	Y	Question text. Markdown is supported.
questionType	'text' | 'photo'	Y	Use text for text answers or photo for image answer URLs.
questionPic	string	N	Image URL displayed with the question.
answerSelectionType	'single' | 'multiple'	Y	Whether the user selects one answer or multiple answers.
answers	string[]	Y	Text answers or image URLs, depending on questionType.
correctAnswer	string | number[]	Y	Correct answer index or indexes. See answer indexing below.
messageForCorrectAnswer	string	N	Message shown for a correct answer when instant feedback is enabled.
messageForIncorrectAnswer	string	N	Message shown for an incorrect answer when instant feedback is enabled.
explanation	string	N	Explanation shown after answering and on the result page.
point	string | number	N	Points assigned to the question.
segment	string	N	Label shown with the question tags.

Answer Indexing

Answer indexes are 1-based.

For a single-answer question, correctAnswer is a string:

{
  answerSelectionType: 'single',
  answers: ['First', 'Second', 'Third'],
  correctAnswer: '2',
}

For a multiple-answer question, correctAnswer is an array of numbers:

{
  answerSelectionType: 'multiple',
  answers: ['First', 'Second', 'Third'],
  correctAnswer: [1, 3],
}

Examples

Shuffle Questions

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

<Quiz quiz={quiz} shuffle />;

Shuffle Answers

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

<Quiz quiz={quiz} shuffleAnswer />;

Instant Feedback

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

<Quiz quiz={quiz} showInstantFeedback />;

Retry Until Correct

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

<Quiz quiz={quiz} continueTillCorrect />;

Reveal Answer On Submit

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

<Quiz quiz={quiz} revealAnswerOnSubmit />;

Previous And Next Navigation

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

<Quiz quiz={quiz} allowNavigation />;

Timer

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

<Quiz quiz={quiz} timer={60} />;

Pause And Resume Timer

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

<Quiz quiz={quiz} timer={60} allowPauseTimer />;

Progress Bar

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

const quizWithProgressColor = {
  ...quiz,
  progressBarColor: '#34d399',
};

<Quiz quiz={quizWithProgressColor} enableProgressBar />;

Disable Landing Synopsis

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

<Quiz quiz={quiz} disableSynopsis />;

Completion Callback

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

const handleComplete = (summary) => {
  console.log(summary);
};

<Quiz quiz={quiz} onComplete={handleComplete} />;

Question Submit Callback

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

const handleQuestionSubmit = ({ question, userAnswer, isCorrect }) => {
  console.log(question, userAnswer, isCorrect);
};

<Quiz quiz={quiz} onQuestionSubmit={handleQuestionSubmit} />;

Custom Result Page

Set showDefaultResult to false when using customResultPage.

import Quiz from 'react-quiz-component';
import { quiz } from './quiz';

const renderCustomResultPage = (summary) => {
  return (
    <div>
      <h2>Custom result page</h2>
      <p>
        You scored {summary.correctPoints} out of {summary.totalPoints}.
      </p>
    </div>
  );
};

<Quiz
  quiz={quiz}
  showDefaultResult={false}
  customResultPage={renderCustomResultPage}
/>;

Props

Name	Type	Default	Required	Description
quiz	Quiz	null	Y	Quiz source object.
shuffle	boolean	false	N	Shuffle questions before rendering.
shuffleAnswer	boolean	false	N	Shuffle answer choices before rendering.
showDefaultResult	boolean	true	N	Show the built-in result page when the quiz ends.
onComplete	(summary: QuestionSummary) => void	undefined	N	Called once when the quiz completes.
customResultPage	(summary: QuestionSummary) => React.ReactElement	undefined	N	Render a custom result page. Use with showDefaultResult={false}.
showInstantFeedback	boolean	false	N	Show correct or incorrect messages after answers are submitted.
continueTillCorrect	boolean	false	N	For single-answer questions, let the user keep trying until the correct answer is selected.
revealAnswerOnSubmit	boolean	false	N	Let the user select an answer before submitting and revealing correctness.
allowNavigation	boolean	false	N	Show previous and next controls so users can move between questions.
onQuestionSubmit	(data: QuestionSubmitData) => void	undefined	N	Called when a question answer is submitted with the question, user answer, and correctness.
disableSynopsis	boolean	false	N	Skip the landing page and start the quiz immediately.
timer	number	undefined	N	Quiz duration in seconds. Must be greater than 0.
allowPauseTimer	boolean	false	N	Allow pausing and resuming when timer is set.
enableProgressBar	boolean	false	N	Show a progress bar above the quiz.

Locale Customization

Add appLocale to the quiz source to override any default text. Placeholders such as <questionLength>, <correctIndexLength>, <correctPoints>, <totalPoints>, <numberOfSelection>, and <marks> are replaced dynamically.

const quiz = {
  quizTitle: 'React Quiz Component Demo',
  questions: [],
  appLocale: {
    landingHeaderText: '<questionLength> Questions',
    question: 'Question',
    startQuizBtn: 'Start Quiz',
    resultFilterAll: 'All',
    resultFilterCorrect: 'Correct',
    resultFilterIncorrect: 'Incorrect',
    resultFilterUnanswered: 'Unanswered',
    nextQuestionBtn: 'Next',
    prevQuestionBtn: 'Prev',
    resultPageHeaderText: 'You have completed the quiz. You got <correctIndexLength> out of <questionLength> questions.',
    resultPagePoint: 'You scored <correctPoints> out of <totalPoints>.',
    pauseScreenDisplay: 'Test is paused. Clicked the Resume button to continue',
    timerTimeRemaining: 'Time Remaining',
    timerTimeTaken: 'Time Taken',
    pauseScreenPause: 'Pause',
    pauseScreenResume: 'Resume',
    singleSelectionTagText: 'Single Selection',
    multipleSelectionTagText: 'Multiple Selection',
    pickNumberOfSelection: 'Pick <numberOfSelection>',
    marksOfQuestion: '(<marks> marks)',
  },
};

Callback Payloads

onComplete(summary) and customResultPage(summary) receive a QuestionSummary object:

type QuestionSummary = {
  numberOfQuestions: number;
  numberOfCorrectAnswers: number;
  numberOfIncorrectAnswers: number;
  questions: Question[];
  userInput: (number | number[] | undefined)[];
  totalPoints: number;
  correctPoints: number;
  timeTaken: number;
};

onQuestionSubmit(data) receives the submitted question result:

type QuestionSubmitData = {
  question: Question;
  userAnswer: number | number[] | undefined;
  isCorrect: boolean;
};

For userInput and userAnswer, single-answer questions use a 1-based number such as 2, multiple-answer questions use a 1-based number array such as [1, 3], and unanswered questions can be undefined.

Development And Contribution

• Clone the repository
• Run npm install
• Run npm run dev
• Run npm run lint
• Make a PR to develop and describe the changes

Demo

The demo is available at https://wingkwong.github.io/react-quiz-component/

License

This project is licensed under the MIT License - see the LICENSE file for details