Configuration

Starlight Quiz needs no configuration to get started: plugins: [starlightQuiz()] is enough. This page lists everything you can change.

Plugin options

The plugin takes a single options object:

astro.config.mjs

starlightQuiz({
  injectStyles: true, // append the bundled theme CSS to Starlight (default true)
});

injectStyles

Type: boolean · Default: true

Appends the bundled theme to Starlight’s customCss. Set to false if you want to provide all quiz styling yourself; import starlight-quiz/styles manually, or write your own.

progressTracker

Type: boolean · Default: true

Shows an aggregate progress widget (answered + correct) in the table of contents, by overriding Starlight’s TableOfContents and MobileTableOfContents. It hides itself on pages without quizzes. Set to false to disable.

progressPosition

Type: 'top' | 'bottom' · Default: 'top'

Whether the progress widget sits above ('top') or below ('bottom') the on-this-page links in the table of contents.

manifest

Type: boolean | string · Default: true

Emit a structured JSON manifest of every quiz to the build output (quiz-manifest.json). Enabled by default; set to false to opt out, or pass a string to choose a different filename. The manifest is parsed from the built HTML, so it captures all quizzes without touching MDX, and is the source consumed by the QTI exporter and the terminal runner.

validate

Type: boolean · Default: true

Fails the build if a quiz has a malformed answer. - [x], - [ ] and - [X] are recognised as answers, and - [] (no inner space) is accepted as an unchecked answer to match mkdocs-quiz. Any other marker (a typo like [o] or a smart bracket pasted from an editor) is rendered by markdown as plain text and would silently never be an answer. Rather than dropping it, the build stops with an error naming the page, the quiz and the offending text. Set to false to ignore such items instead.

quizDefaults

Type: Partial<{ autoSubmit; disableAfterSubmit; showCorrect; shuffle; confetti; autoNumber }> · Default: all true except shuffle and autoNumber

Site-wide defaults for quiz behaviour, applied to every <Quiz> and <QuizResults> that doesn’t set the matching prop itself, so you can change behaviour everywhere without editing each quiz. An explicit prop on a component always wins.

astro.config.mjs

starlightQuiz({
  quizDefaults: {
    confetti: false, // no confetti anywhere
    autoSubmit: false, // always show a Submit button
  },
});

<Quiz> props

Each behaviour prop falls back to the quizDefaults plugin option, then to the built-in default below.

Prop	Type	Default	Description
id	string	—	Stable id for persistence (falls back to a hash of title).
title	string	—	Heading shown above the quiz.
shuffle	boolean	false	Shuffle answer order on load.
autoSubmit	boolean	true	Single-choice: grade on click/tap. false shows a Submit button.
disableAfterSubmit	boolean	true	Lock after submitting; false shows a reset button.
showCorrect	boolean	true	Reveal the correct answer(s) after a wrong submission.
autoNumber	boolean	false	Prefix with a numbered “Question N” heading. See Auto-numbering.

autoSubmit

Type: boolean · Default: true

Single-choice quizzes grade as soon as an answer is clicked or tapped, with no Submit button. Keyboard users arrowing through the options are not locked in. Only an explicit click, tap or Space activation submits. Set false to show a Submit button instead. Multiple-choice and fill-in-the-blank quizzes always use a Submit button.

disableAfterSubmit

Type: boolean · Default: true

After submitting, the quiz is locked and cannot be changed. Set false to show a Try again reset button so readers can retry.

showCorrect

Type: boolean · Default: true

When a reader submits a wrong answer, the correct answer(s) are highlighted. Set false to tell them only whether they were right or wrong, without revealing the answer.

Label overrides

Every UI string can be overridden per quiz, useful outside Starlight or for custom wording: submitLabel, resetLabel, correctLabel, incorrectLabel and tryAgainLabel.

<Quiz submitLabel="Check answer" correctLabel="Spot on!">
  …
</Quiz>

<QuizResults> props

Prop	Type	Default	Description
confetti	boolean	true	Fire confetti on a first-time completion (score ≥ 10%). Pass confetti={false} to disable.
titleLabel	string	—	Override the completed-panel title.
progressLabel	string	—	Override the in-progress “Quiz Progress” heading.
answeredLabel	string	—	Override the phrase after the answered / total count.
correctLabel	string	—	Override the word after the correct count.
resetLabel	string	—	Override the reset-all button label.

<QuizIntro> props

See Intro panel for what this component does.

The intro message is best set by passing content in the default slot (<QuizIntro>…</QuizIntro>), which accepts markdown. The textLabel prop is a plain-string fallback for vanilla Astro and i18n overrides.

Prop	Type	Default	Description
textLabel	string	—	Plain-string intro text (the default slot takes precedence).
resetLabel	string	—	Override the reset-all button label.

<QuizProgress> props

Under the plugin, the progress widget is injected into the table of contents for you. You can also import and place <QuizProgress /> yourself, useful in vanilla Astro or to control where it appears. It hides itself on pages with no quizzes. (The compact badge shown in the mobile ToC bar is an internal variant of this widget and isn’t a separate public component.)

Prop	Type	Default	Description
showHeading	boolean	true	Render the “Quiz Progress” heading (set false for compact placements).
headingLabel	string	—	Override the heading.
answeredLabel	string	—	Override the word after the answered count.
correctLabel	string	—	Override the word after the correct count.
resetLabel	string	—	Override the reset button label.

Custom styling

Quizzes are themed with CSS custom properties (--slq-accent, --slq-radius and more) that default to your Starlight colour tokens, so they follow your site theme out of the box, and every element carries a stable class name you can target. See Custom CSS for the full variable reference and class hooks.

Internationalisation

Starlight Quiz ships translations for 13 languages and resolves each label as: explicit prop → Starlight translation for the current locale → bundled English. See Translations for the full list and how to add a language.