# 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:

```js title="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.

```js title="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`](#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](/starlight-quiz/guides/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`.

```mdx
<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](/starlight-quiz/guides/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](/starlight-quiz/guides/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](/starlight-quiz/guides/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](/starlight-quiz/guides/translations/) for the full list and how
to add a language.