State and actions

Treat state as read-only; use actions to change it. Question indexes are zero-based and answer numbers are one-based, matching callback answer numbers.

Actions return { ok: true } or { ok: false, reason }; blocked actions do not change answers or navigation. Timed actions first reconcile elapsed time and may complete an expired quiz; a reset with invalid options replaces the session as described below. reason is a typed BlockedReason such as invalid-state, disabled-answer, or incomplete-quiz.

Immediate multiple-answer questions are evaluated when the required selection count is reached. continueTillCorrect applies to immediate single-answer questions. With showCorrectAnswer, all correct choices receive answer-level feedback after an evaluated immediate attempt, including an incorrect attempt. Multiple-answer questions wait for the required selection count. Unselected correct choices remain unselected; this does not change scoring or disable retries. In deferred mode, correctness is tracked for scoring but no correctness feedback is shown during selection, even with showCorrectAnswer.

Selection and submission rulesCopy Anchor Link

In immediate mode, selected answers are disabled and cannot be deselected. A finished question cannot be edited on revisit. A question whose time budget expired cannot be edited in either mode. In deferred mode, single-answer choices can be replaced and multiple-answer choices can be toggled until completion.

canSubmit requires an active session and a finished answer for every non-expired question, independently of allowNavigation. A question whose questionTimer expired is locked and does not block submission. Multiple-answer questions require the requested selection count in both immediate and deferred modes; only an exact match scores points. A retry-until-correct question needs a correct attempt. Without allowNavigation, canGoNext applies the same completion rule to the current question, so too few or too many deferred selections block advancing. With allowNavigation, users can still skip and revisit incomplete questions.

The headless submitQuiz() action can submit from any question when canSubmit is true. The default component submits through Next on the final question. Timer expiry completes automatically even when canSubmit is false. quitQuiz() explicitly permits early completion when canQuit is true, without relaxing normal submission requirements. Partial multiple-answer selections count as incorrect; untouched questions remain unanswered. Pending answer callbacks run before onComplete, once per completion. Headless consumers supply their own confirmation UI.

setResultFilter() works in every non-invalid status; it does not require completion. The unanswered filter means no input, not “no evaluated outcome.”

Deferred results in custom UIsCopy Anchor Link

Deferred mode hides answer-level correctness feedback until completion. It still updates outcome, correct, incorrect, and summary for scoring while answers are being edited. Avoid displaying those scoring fields before completion if your UI should conceal correctness. After completion, answers[].feedback identifies all correct choices and any incorrect selected choices.

Blocked actionsCopy Anchor Link

Check result.ok before reading result.reason:

const result = actions.submitQuiz();
if (!result.ok) console.log(result.reason);

Blocked transitions preserve answers and navigation. Timer accounting happens before an action is checked, so even a blocked action can update elapsed time or complete an expired session. When the latest options are invalid, reset() returns invalid-quiz and replaces the session with validation errors.