Quiz Block

Quiz Block Multi-step quiz plugin using Gutenberg blocks.
A Human Made project.

https://github.com/user-attachments/assets/1146033f-d0f2-4f80-9517-635314ab15be

Features

• One question at a time with animated progress bar
• Multiple-choice alternatives with radio selection for correct answer in the editor
• Correct/incorrect feedback panels — supports any core WordPress block (paragraphs, images, videos, etc.)
• Optional supplementary content block between question and choices
• Customisable completion screen with show/hide toggle and background colour picker
• Full i18n support
• Accessible: :focus-visible, ARIA attributes, prefers-reduced-motion

Block Structure

[hmquiz/quiz]
  ├── [hmquiz/question]  (repeatable)
  │     ├── [hmquiz/question-content]         ← optional images, videos, text
  │     ├── [hmquiz/feedback type="correct"]  ← any blocks, shown on correct answer
  │     └── [hmquiz/feedback type="incorrect"]
  └── [hmquiz/quiz-complete]                  ← optional completion screen

How It Works

The plugin adds five custom Gutenberg blocks. When a visitor opens a page containing a quiz, JavaScript takes over: it shows one question at a time, updates a progress bar, reveals feedback after each answer, and shows a completion screen at the end — all without any page reload.

Creating a Quiz

1. Add the Quiz block

In the block inserter, search for Quiz (under the Quiz category) and add it to your post or page. This is the outer container — all other quiz blocks live inside it.

2. Add questions

Inside the Quiz block, add one or more Quiz Question blocks. Each question has:

• Question text — a rich-text field at the top of the block.

• Alternatives — multiple-choice options listed below the question text. Click Add Alternative to add more. Use the ↑ / ↓ arrows to reorder them. Select the radio button next to an option to mark it as the correct answer.

  

• Question Content (optional) — an inner section where you can add any WordPress block (image, video, paragraph, etc.) to accompany the question. It appears between the question text and the answer choices on the frontend.

  

• Correct / Incorrect Feedback — two inner panels where you can add any blocks. The matching panel is shown to the visitor after they answer.

  

3. Add a completion screen (optional)

After your last Question block, add the Quiz Completion Screen block. You can:

• Write any content inside it (heading, paragraph, image, etc.).
• Toggle it on or off in the block settings sidebar.
• Pick a background colour in the sidebar.

If you don't add this block (or toggle it off), the quiz simply ends silently after the last question.

4. Publish

Save or publish the post. The quiz is fully interactive on the frontend — no shortcodes, no page builders, no configuration needed.

Requirements

• WordPress 5.9+
• PHP 7.4+

Installation

Download the latest release ZIP from the Releases page, then in WordPress admin go to Plugins → Add New → Upload Plugin.

Development

Setup

composer install
npm install
npm run build

Linting

# PHP (PHPCS)
composer lint

# PHP (PHPStan level 8)
composer phpstan

# JavaScript (ESLint)
npm run lint:js

# CSS (Stylelint)
npm run lint:css

# All at once
npm run lint

Release Process

Merges to main automatically build to the release branch. A project may track the release branch using Composer to pull in the latest built beta version.

Commits on the release branch may be tagged for installation via Packagist and marked as releases in GitHub for manual download, using a manually-dispatched "Tag and Release" GH Actions workflow.

To tag a new release:

1. Choose the target version number using semantic versioning.
2. Check out a prepare-v#.#.# branch and bump the Version in the quiz-block.php PHPDoc header.
3. Open a pull request titled "Prepare release v#.#.#".
4. Review and merge the "Prepare release" pull request.
5. Wait for the release branch to update with the build that includes the new version number.
6. On the "Tag and Release" GH Action page:
   • Click "Run workflow" in the workflow_dispatch banner.
   • Fill out the "Version tag" field with your target version number. This must match the Version in quiz-block.php. Use the format v#.#.#.
   • Click "Run workflow" to apply the specified tag to the release branch.

Once the workflow completes, the new version is tagged and listed in releases.

Local Environment

This project uses wp-env to run a lightweight, containerized WordPress instance at localhost:3009 for testing purposes. The default username for the localhost environment is admin, with the password password.

These commands can be used to interact with the environment:

Command	Purpose
npm run env:start	Start the local environment at http://localhost:3009
npm run env:stop	Turn off the local environment
npm run env:cli -- wp ...	Run WP-CLI commands within the environment
npm run env:logs	Open (and tail) the error logs for the application‡
npm run env:db	Open the database in the mysql command line
npm run env:destroy	Fully destroy the local environment (deletes container database)

‡ This command deliberately filters out GET/OPTIONS/HEAD/POST/PUT access log entries

License

GPL-2.0+