React Quiz Component

TypeScript types

Find the public TypeScript types for quiz data, component props, headless configuration, state, actions, and callback results. Import them directly from the package root and use the engine declarations as a reference for custom integrations.

Import types with import type from react-quiz-component. There is no headless subpath.

TypesPurpose
Quiz, Question, QuestionType, AnswerSelectionTypeQuiz data and selection modes.
AppLocaleAll built-in locale keys. Use Partial<AppLocale> for overrides.
QuizPropsProps for the default component.
QuestionSummary, QuestionSubmitData, UserAnswerResult and callback payloads.
UseQuizOptions, QuizProviderPropsHook and provider configuration.
QuizControllerThe { state, actions } value returned by both hooks.
QuizState, QuizStatusRead-only state and session status.
QuestionState, QuestionAttempt, AnswerState, AnswerFeedbackPer-question attempts, answers, and feedback.
QuizActions, ActionResult, BlockedReasonTyped actions and their success/failure results.
ResultFilter'all', 'correct', 'incorrect', or 'unanswered'.

Engine declarations

These declarations describe the current engine API. See the quiz data, component props, and callback payloads pages for the related data types.

import type { ReactNode } from 'react';
import type {
  AppLocale,
  Question,
  QuestionSummary,
  Quiz,
} from 'react-quiz-component';

export type UserAnswer = number | number[] | undefined;
export type QuizStatus = 'idle' | 'active' | 'paused' | 'completed' | 'invalid';
export type AnswerFeedback = 'correct' | 'incorrect' | null;
export type ResultFilter = 'all' | 'correct' | 'incorrect' | 'unanswered';
export interface QuestionSubmitData {
  question: Question;
  userAnswer: UserAnswer;
  isCorrect: boolean;
}
export interface UseQuizOptions {
  quiz: Quiz;
  shuffle?: boolean;
  shuffleAnswer?: boolean;
  continueTillCorrect?: boolean;
  revealAnswerOnSubmit?: boolean;
  showCorrectAnswer?: boolean;
  allowNavigation?: boolean;
  timer?: number;
  questionTimer?: number;
  allowPauseTimer?: boolean;
  autoStart?: boolean;
  onComplete?: (summary: QuestionSummary) => void;
  onQuestionSubmit?: (data: QuestionSubmitData) => void;
}
export interface QuizProviderProps extends UseQuizOptions {
  children: ReactNode;
}
export interface AnswerState {
  readonly answerNumber: number;
  readonly value: string;
  readonly selected: boolean;
  readonly disabled: boolean;
  readonly feedback: AnswerFeedback;
}
export interface QuestionAttempt {
  readonly userAnswer: UserAnswer;
  readonly isCorrect: boolean;
}
export interface QuestionState {
  readonly question: Question;
  readonly index: number;
  readonly userAnswer: UserAnswer;
  readonly attempts: readonly QuestionAttempt[];
  readonly outcome: AnswerFeedback;
  readonly feedback: AnswerFeedback;
  readonly answered: boolean;
  readonly timedOut: boolean;
  readonly timeRemaining: number | undefined;
  readonly answers: readonly AnswerState[];
}
export interface QuizState {
  readonly status: QuizStatus;
  readonly errors: readonly string[];
  readonly quiz: Quiz;
  readonly questions: readonly Question[];
  readonly currentQuestionIndex: number;
  readonly currentQuestion: Question | undefined;
  readonly currentQuestionState: QuestionState | undefined;
  readonly questionStates: readonly QuestionState[];
  readonly userInput: readonly UserAnswer[];
  readonly answers: readonly AnswerState[];
  readonly feedback: AnswerFeedback;
  readonly correct: readonly number[];
  readonly incorrect: readonly number[];
  readonly unanswered: readonly number[];
  readonly canStart: boolean;
  readonly canGoNext: boolean;
  readonly canGoPrevious: boolean;
  readonly canSubmit: boolean;
  readonly canQuit: boolean;
  readonly canPause: boolean;
  readonly canResume: boolean;
  readonly allowNavigation: boolean;
  readonly progress: number;
  readonly timer: number | undefined;
  readonly questionTimer: number | undefined;
  readonly questionTimeRemaining: number | undefined;
  readonly timeRemaining: number | undefined;
  readonly timeTaken: number;
  readonly summary: QuestionSummary;
  readonly appLocale: AppLocale;
  readonly resultFilter: ResultFilter;
  readonly filteredResults: readonly QuestionState[];
}
export type BlockedReason =
  | 'invalid-quiz'
  | 'invalid-state'
  | 'invalid-answer'
  | 'disabled-answer'
  | 'invalid-index'
  | 'navigation-disabled'
  | 'answer-required'
  | 'incomplete-quiz'
  | 'timer-disabled'
  | 'invalid-filter';
export type ActionResult = { ok: true } | { ok: false; reason: BlockedReason };
export interface QuizActions {
  start: () => ActionResult;
  selectAnswer: (answerNumber: number) => ActionResult;
  nextQuestion: () => ActionResult;
  previousQuestion: () => ActionResult;
  goToQuestion: (index: number) => ActionResult;
  submitQuiz: () => ActionResult;
  quitQuiz: () => ActionResult;
  pauseTimer: () => ActionResult;
  resumeTimer: () => ActionResult;
  setResultFilter: (filter: ResultFilter) => ActionResult;
  reset: () => ActionResult;
}
export interface QuizController {
  state: QuizState;
  actions: QuizActions;
}

Callbacks and results

Handle submitted answers and completed quizzes using the callback payloads shared by the default component and headless API. Learn when events fire, how deferred answers and timeouts affect delivery, and how to interpret and retain results.

Default quiz

Try the default Quiz component with instant feedback, a progress bar, and a final score. Use the runnable component source and accompanying quiz data to add a complete, styled quiz to your application.

On this page

Engine declarations