A11y Quiz Form

Live demo: Single answer

Choose an answer and check it. A wrong first attempt reveals targeted feedback; a correct or final answer reveals all explanations.

Practice · 2 attempts · Radio buttons

Multiple answers — Checkbox quiz

Practice · 2 attempts · Checkboxes

Exam mode — One attempt, no hint

Exam · 1 attempt · No hint

Review mode — Already answered

Review · Read-only · All explanations visible

Focused standalone examples

Use these smaller pages when you need one behavior, configuration boundary, or lifecycle question without the full documentation page around it.

Installation

The repository is configured for npm packaging. Confirm registry availability before using the package name in a production install.

npm install a11y-quiz-form

pnpm add a11y-quiz-form

yarn add a11y-quiz-form

Basic usage

Supply the semantic form markup. The plugin adds feedback behavior and live-region relationships; it does not generate the question or answers.

HTML

<form class="a11y-quiz" data-a11y-quiz novalidate>
  <fieldset class="a11y-quiz__fieldset">
    <legend class="a11y-quiz__question">Which element is a button?</legend>
    <p class="a11y-quiz__instruction">Choose one answer.</p>

    <div class="a11y-quiz__answers">
      <div class="a11y-quiz__answer" data-correct="true">
        <label class="a11y-quiz__answer-label">
          <input class="a11y-quiz__input" type="radio" name="answer" value="button">
          <span class="a11y-quiz__answer-text">&lt;button&gt;</span>
        </label>
        <p class="a11y-quiz__explanation" hidden>A button has native semantics.</p>
      </div>
    </div>

    <p class="a11y-quiz__status"></p>
    <div class="a11y-quiz__actions">
      <button type="submit">Check answer</button>
      <button type="button" data-quiz-show-answer hidden>Show answer</button>
      <button type="button" data-quiz-reset hidden>Try again</button>
    </div>
  </fieldset>
</form>

JavaScript

import { createQuizForm } from "a11y-quiz-form";
import "a11y-quiz-form/styles.css";

const form = document.querySelector("[data-a11y-quiz]");

if (form instanceof HTMLFormElement) {
  createQuizForm(form, { maxAttempts: 2 });
}

See the focused basic example for a complete standalone file.

Options

Pass options to createQuizForm() or use the matching data-* attributes. Programmatic options take precedence and invalid values fall back to the defaults.

Localization

Pass a partial typed message catalog. Strings work for fixed copy; callbacks receive attempt, maxAttempts, and remainingAttempts for grammar and pluralization. Missing, empty, invalid, or throwing overrides safely use the existing English default.

import { createQuizForm, type QuizFormMessages } from "a11y-quiz-form";

const messages = {
  validationRequired: "Elige al menos una respuesta.",
  correct: ({ attempt }) => `Correcto en el intento ${attempt}.`,
  incorrectRetry: ({ remainingAttempts }) =>
    remainingAttempts === 1
      ? "Queda un intento."
      : `Quedan ${remainingAttempts} intentos.`,
} satisfies QuizFormMessages;

createQuizForm(form, { messages });

Keep live-region and validation messages concise, meaningful, and non-empty. Include the result or action and any remaining-attempt context needed without relying on nearby visual content. Callbacks intentionally receive attempt counts, not selected values. Do not close over or place private response data, personal information, or secure answer material in messages because the text can be visible and announced by assistive technology.

The exported QuizFormMessages, QuizFormMessageContext, and QuizFormMessageKey types define the catalog. See the repository README for the complete message-key table and English default purposes.

API and events

Events

Events dispatch synchronously from the form, bubble, do not cross a shadow boundary, and are non-cancelable. Their detail includes instance and the compatibility alias quiz, plus the fields below.

Guaranteed sequences include init → ready, check → correct → complete, check → incorrect → retry, and check → incorrect → complete. When reveal first completes a run it emits reveal → complete; a later permitted reveal emits only reveal.

Accessibility behavior

Keyboard interaction

Styling hooks

.a11y-quiz {
  --a11y-quiz-color-action-bg: #5b21b6;
  --a11y-quiz-color-action-hover: #4c1d95;
  --a11y-quiz-color-focus-ring: #fbbf24;
  --a11y-quiz-radius: 0.75rem;
}

Limitations and support

• The plugin manages one question per form; it does not aggregate scores across a quiz or persist results.
• Question and answer markup must follow the documented class and data-attribute contract.
• Correct answers are stored in client-side data-correct attributes. Exam mode changes interaction, but it is not a secure assessment system.
• The plugin does not sanitize author-provided question, hint, or explanation HTML.
• Screen reader output still depends on correct, concise content and should be tested with the combinations your product supports.
• No formal browser compatibility matrix or WCAG conformance claim is included. The build targets modern ESM-capable browsers.

Treat this package as an interaction layer. Content design, answer quality, localization, end-to-end assistive-technology testing, and server-side assessment security remain the integrating application’s responsibility.