HD Quiz Documentation

HD Quiz is a free quiz builder and one of the top-rated plugins on WordPress.org.

You can request free support, but please consider looking at the documentation first. Your Answer may lie within.

Common Features

• Free WordPress quiz plugin with timer functionality
• Two quiz types: traditional scored quizzes, and personality quizzes (“Which Harry Potter character are you?”)
• Unlimited number of quizzes, questions, and answers
• Multiple question formats (multiple choice text/image, select all that apply text/image, text input, headings)
• Weighted answers — award custom point values per answer, even negative points
• Secure mode — optional server-side answer validation to make cheating significantly harder
• Ability to share quiz results across social media (X/Twitter, Facebook, Bluesky, and Web Share)
• Featured images, tooltips, “before question” media content, reusable questions, and so much more!

Common Questions

Demo / Tutorial Video

Creating a Quiz

Go to HD Quiz ⇾ Quizzes, enter the name of your new quiz, and choose the Quiz Type:

• General / Scored – The default quiz type, meant for traditional quizzes with scores, a pass percentage, and pass/fail results.
• Personality – Meant for quizzes similar to “Which Harry Potter Character are you?”. Instead of correct answers, each answer awards points towards an outcome, and the highest-scoring outcome is the final result.

The quiz type is chosen at creation and determines which settings and question types are available, so make sure to pick the right one!

Displaying a quiz

HD Quiz uses shortcodes to render quizzes, so you can place a quiz almost anywhere on your site. To find the shortcode for a quiz, select Quizzes in the left menu — each quiz in the list shows its shortcode, which looks like:

[HDquiz quiz="123"]

The quiz attribute is the quiz ID. Copy and paste the shortcode into any page or post.

If using Gutenberg, you can add the HD Quiz Block instead and simply select your quiz from a dropdown.

Only one quiz can be displayed per page. If a quiz shortcode is encountered somewhere unusual (a category page, search results, an archive, a sidebar, etc.), HD Quiz will instead print a “QUIZ START” button that links to the quiz’s own page. This behaviour can be disabled with the HDQ_REDIRECT definition (see Advanced below). Quizzes are also intentionally not rendered on AMP pages or inside Elementor’s editor view.

Settings Page

Global options that affect all quizzes can be found under HD Quiz ⇾ Settings. It is recommended that you pay this page a visit after first installing HD Quiz.

General

• I ❤️ HD Quiz – Love HD Quiz? Enable this feature to add a subtle link to the quiz results pointing towards HD Quiz. This is a great way to help support us!

Social Media Tab

• Allow social media sharing – Enabled by default. Disable this to remove the social media share icons from quiz results across all quizzes.
• Enable enhanced Facebook sharing – An experimental feature that works by creating a dedicated share page just for Facebook (Facebook no longer allows sharing of custom/dynamic content directly). This will not work for all users, and support is not offered for it.
• Twitter/X handle – Enter your handle (do NOT include the @ symbol) so that shared posts mention you as the author.
• Share text [general / scored] – The share text used for scored quizzes. You can use the variables %quiz% (quiz name) and %score% (user’s score as a fraction).
• Share text [personality] – The share text used for personality quizzes. Here, %score% displays the outcome title the user received.

The share section on quiz results includes buttons for X (Twitter), Facebook, Bluesky, and Web Share. The Web Share button only appears for compatible browsers — it is primarily used by smartphones to share text/links to apps such as Instagram, WhatsApp, Text Message, and Email.

Other Options

• Allow authors access to create quizzes – By default, only Admins can create and edit quizzes. Enabling this allows Authors to create quizzes as well. Authors can only edit their own quizzes; enabling this also grants the Editor role access to edit all quizzes.
• Show results as percentage – Enabled by default. Disable if you want to hide the percentage score in the results and only show the score as a fraction (x / y).
• Replace the_content filter for quizzes – Enabled by default. HD Quiz uses a custom version of the_content filter to print content to the page (extra text and result text). This prevents other plugins from automatically injecting their own content (social buttons, related posts, ads) into your quiz results. Disable this if you want to allow other plugins to add their content again.
• Enable secure mode – Uses your server to validate answers so that correct answers are never exposed in the page source. Scored quizzes only. See “Can I stop users from cheating?” above for full details.
• Adset Code – Paste your ad code here and HD Quiz will place it after every 5th question. DO NOT USE if you are already displaying auto ads on your site. How the ad appears is entirely based on the ads and ad networks themselves, and some ads do not play nice with pagination (they do not like loading on the page hidden). If using JavaScript, keep all of your code on one line to stop WordPress from adding paragraph tags where you don’t want them.

Translations

Do you need to rename a button? Do you need to translate HD Quiz into your language? This is the section you need. You can rename:

• “Finish” button
• “Next” button
• “Previous” button
• “Results” text
• “QUIZ START” text (used when a timer is enabled, or for direct links to the quiz on category/search pages)
• “enter answer here” (placeholder for the Text Based Answers question type)
• “Select all that apply:” text
• “Submit” button (appears with the Select All That Apply question type when either “Immediately mark answer as correct or incorrect” or timer-per-question is enabled)

Quiz Settings — General / Scored Quizzes

To edit your individual quiz settings, select your desired quiz, then select the QUIZ SETTINGS tab.

Results

• Quiz pass percentage – The minimum percentage of questions a user needs to get correct in order to see the Quiz Pass Content. Default is 70%.
• Hide questions after quiz completion – Automatically hide all the questions once a quiz has been completed so that only the results are shown.
• Quiz pass content – Custom content to show if a user passes the quiz. You can also place shortcodes, images, videos, buttons etc.
• Quiz fail content – Custom content to show if a user fails the quiz.
• Quiz redirect URL – Automatically redirect to another page on quiz completion.
• Quiz redirect delay – How many seconds to wait after results before redirecting (0–100).

Marking

• Highlight questions as correct or incorrect – Enabled by default. Shows the user which questions they got right and which they got wrong on quiz completion.
• Show correct answers on completion – Goes the extra step and shows what the correct answer was in the case that the user selected the wrong one.
• Immediately mark answer as correct or incorrect – Marks the question as soon as an answer has been selected.
• Stop users from changing their answers – Once an answer has been selected, it cannot be changed.
• Always show extra content – Each question can have “Extra content” that normally appears only if the user got the question wrong. Enable this so it appears even when the answer was correct.
• Force users to answer all questions – Checks that every question has been answered before submission. NOTE: will not work with timer-per-question; if the user does not answer in time, that question is marked as incorrect.

Timer

If the timer is enabled, the quiz will be hidden behind a “START QUIZ” button so that the timer does not count down before the user is ready. You can rename this button from HD Quiz ⇾ Settings.

• Timer / countdown – The total time in seconds (e.g. 3 minutes = 180). The timer will NOT work if the WP Pagination feature is being used.
• Per question – Enable if you want the timer to apply per question instead of to the entire quiz.
  • BONUS: If you want to force your users to answer every question, you can also just use the dedicated “Force users to answer all questions” setting under Marking.

Advanced

If you are having trouble with either the Randomization options or the Pool of Questions, make sure you do not have page caching enabled on the pages with quizzes.

• Share quiz results – Show the social media share icons in this quiz’s results. If the global “Allow social media sharing” setting is disabled, then this will be disabled too.
• Show results above or below quiz – By default, results appear at the top of quizzes. HD Quiz automatically scrolls to the results on completion, so keeping the default is recommended if you are using any kind of marking — it lets the user scroll back down past the questions to review their answers.
• Randomize question order – Randomizes the order of all questions on every page load.
• Randomize answer order – Randomizes the order that each answer is displayed.
• Use pool of questions – One of the coolest and most underrated features of HD Quiz. If you have, for example, 100 questions added to a quiz but set this to 20, HD Quiz will randomly grab 20 questions from that pool on each load. Combined with “Randomize answer order”, this allows for a near-unlimited number of quiz variations! Set to 0 or leave blank to disable.
• Force paginate all questions – Ignores the per-question Paginate setting and forces pagination on for every question. Great for quickly turning a long quiz into a one-question-per-page experience.
• WP pagination – Forces a set number of questions per page with a full page load between question groups. This feature is not compatible with several other features such as randomization and timers. WARNING: This feature is deprecated and will be discontinued sometime in the future. To continue using it, you will need to add define('HDQ_ENABLE_WP_PAGINATION', true); to your theme’s functions.php file. Unless you have a specific use case (such as increasing page views for ad revenue), use the per-question Paginate option instead.
• Rename quiz – Rename this quiz. The quiz ID (and therefore your shortcode) stays the same.

Quiz Settings — Personality Quizzes

Personality quizzes have their own, simpler settings.

Results (Outcomes)

Here you define your Outcomes — the possible results of the quiz (e.g. “Gryffindor”, “Slytherin”…). Each outcome has a title and its own content (text, images, video, etc.).

Each answer in your questions awards points towards one of these outcomes. The outcome with the highest score will be the final result. In the event of a tie, the first possible outcome wins.

Renaming an outcome is the same as creating a new one, so remember to edit your questions to point at the correct outcomes afterwards.

Advanced

Personality quizzes share most of the same Advanced options as scored quizzes: Share quiz results, Show results above or below quiz, Randomize question order, Randomize answer order, Force users to answer all questions, Hide questions after quiz completion, Quiz redirect URL / delay, and Rename quiz.

Note that Personality quizzes do not have marking, timers, pass percentages, or the pool of questions feature.

Question Settings

Question Title

It is recommended to only use plain text for question titles — it usually results in a better user experience. However, for the stubborn tinkerers, you are able to use basic HTML formatting in the title such as <strong>, <em>, <sup>, <sub>, and <code>.

Question Types

For General / Scored quizzes:

• Multiple choice – text – Default multiple choice question type.
• Multiple choice – image – Multiple choice, but each answer is also an image.
• Select all that apply – text – Like multiple choice, but you can set more than one correct answer. The user will need to select all of the correct answers to be awarded the point (unless using weighted answers — see below).
• Select all that apply – image – Same as above, but with image answers.
• Text-based answers – The user needs to type in their answer. Compatible with stemming: add an asterisk * to the end of a word to accept all extensions of that word. For example, hop* would accept “hop, hope, hopping” etc. as correct answers.
• Question as title – Not a question! Useful if you want to separate your questions into categories by using a question as a heading.

For Personality quizzes:

• Multiple choice – text – Each answer awards points towards one of your outcomes.
• Multiple choice – image – Same, with image answers.
• Question as title – Section heading.

Main tab options

• Paginate – Start a new page with this question. This question, and all questions below it, will be hidden behind a “Next” button. Great for categorizing questions or breaking longer quizzes into shorter bites. (You can also force this on for all questions from quiz settings ⇾ Advanced ⇾ Force paginate all questions.)
• Weighted answers – If enabled, each answer can be given its own point value — even negative points! Instead of a single “correct” answer, every answer contributes its own score. Works with both scored and personality question types. Not all question types are compatible with this feature (e.g. text-based answers).

You can have up to ten (10) answers per question by default (see HDQ_MAX_ANSWERS below to change this). When editing a question, you can use the next/previous question buttons to quickly move between questions in the quiz without returning to the question list.

Extra tab

First off, I’m not a fan of the name “Extra”. I feel like many of you think that there is nothing important behind here, but there is some cool stuff hidden on this tab!

• Tooltip – Add a tooltip to the question title to provide additional information or context.
• Question featured image – Set a featured image for the question. The image will appear inside the question, above the question title.
• Extra content – Content that appears if the user got the question wrong. There is a quiz setting (“Always show extra content”) to force this to appear even if the user gets the question correct. Great for explaining why the correct answer is correct.
• Before question content – Content that appears before the question title and after the featured image. This is a great place to add audio or video to your question. Please note that how your media looks and behaves can be modified by your theme or another plugin, so full support cannot be offered for this feature.

Questions can belong to multiple quizzes

A cool thing about how HD Quiz is built is that it works off of a Post ⇾ Category relationship. Just like how you can add a post to many categories on your WordPress blog, you can add the same question to multiple quizzes with HD Quiz!

Tools

The HD Quiz ⇾ Tools page contains utilities that most of you will never need, but that are here to help you out when needed.

Question CSV Uploader

Bulk-import questions from a CSV (comma separated values) file. This tool is ONLY for General/Scored quizzes — it is not compatible with the Personality quiz type.

The importer only sets the basic values needed for a question (all imported questions are created as Multiple choice – text). You will need to manually set quiz settings, or extra question options such as question type and images, after the import has completed.

CSV format: Fields should use a comma , as a delimiter, and strings should be encapsulated in double quotes " if the string contains a comma. The fields, in order, are:

Quiz Name, Question Title, Answer 1, Answer 2, ... Answer 10, Correct Answer

The Correct Answer field should be an integer that corresponds to which answer is correct. So if Answer 3 is the correct answer, set Correct Answer to 3. An optional final field can contain the question’s “Extra content” text. If the named quiz does not exist yet, it will be created for you.

An example CSV file is available for download on the importer page — use it as a reference. Note: if you need to export and import existing questions between sites, use WordPress’ native import/export tool instead; this tool is for bulk adding brand new questions.

Questions Custom Post Type Admin

HD Quiz is built using a Custom Post Type (questions) and a Custom Taxonomy (quizzes). This tool takes you to the raw WordPress admin list of all questions, which you can use to bulk delete questions, or bulk add questions to a quiz.

Quizzes Custom Taxonomy Admin

Fast access to delete multiple quizzes at the same time. Just note that deleting a quiz keeps its questions — pair this with the Questions CPT Admin tool above to fully clean up your database.

Advanced

You’ve made it this far? Fantastic! It’s just you and me now, so we can get into some of the good stuff. The hidden secrets of HD Quiz. For some of these you will need to be able to add code to your site, so as ALWAYS, back up any file you edit first!

Definitions

Set any of these in your theme’s functions.php file.

HDQ_REDIRECT – Automatically redirects HD Quiz to the proper page if a quiz loads in a weird place such as a category page, search page, sidebar, etc. This is done to ensure the best compatibility, since only one quiz can be on a page at a time. If for whatever reason you need to disable this, set define('HDQ_REDIRECT', false);.

HDQ_PER_PAGE – Sets the pagination limit for the question list in the admin area. If you have a lot of questions added to a single quiz, the page can get long. Defaults to 50. Example: define('HDQ_PER_PAGE', 200);.

HDQ_MAX_ANSWERS – Sets the max number of answers per question. By default this is 10. Example: define('HDQ_MAX_ANSWERS', 15);.

HDQ_FORCE_ORDER – Force the query order (order of questions) on quizzes. Useful if you have another plugin or theme function that is overriding query orders. Defaults to false.

HDQ_DISABLE_PREV_BUTTON – Set to true to remove the “Previous” button from paginated quizzes, so users can only move forward. Example: define('HDQ_DISABLE_PREV_BUTTON', true);.

HDQ_ENABLE_WP_PAGINATION – The WP Pagination quiz setting is deprecated. Set define('HDQ_ENABLE_WP_PAGINATION', true); for continued use of the feature.

Actions

hdq_before – Add custom content before a quiz. Receives $quiz_id.

hdq_after – Add custom content after a quiz. Receives $quiz_id.

hdq_after_featured_image – Add custom content after the question’s featured image and before the question title. Super useful for adding custom media like video. Receives $question, an array with relevant question data such as question_id, quiz_id, question_type, and all other related data such as the question answers and settings.

hdq_before_finish_button – Add custom content immediately before the quiz’s Finish button. Receives $quiz_id.

hdq_results_after_content – Add custom content inside the results section, after the pass/fail (or outcome) content. Receives $quiz_id.

hdq_share_content – Add custom content inside the social share section of the results. Receives $quiz_id.

hdq_init – JavaScript-facing lifecycle hook fired when a quiz initializes on the page.

hdq_before_submit – Fires on quiz completion, before submission/marking. Useful for serverside validations via addons.

hdq_submit – Fires on quiz completion/submit.

Filters

hdq_build_quiz – Return true or false to control whether the quiz should build. Receives the current value and $quiz_id.

hdq_set_question_number_symbol – Override the question number symbol (defaults to #).

hdq_filter_question_data – Filter the full data array of a question before it is rendered. Receives $data, $question_id, $quiz_id.

hdq_before_quiz_data – Filter the assembled quiz data (settings, question order, etc.) before the quiz template renders.

hdq_extra_question_data – Add extra data attributes to a question’s wrapper element. Receives an array, $question, and $quiz_id.

hdq_add_question_type – Register your own custom question types. HD Quiz will look for functions named hdq_question_type_{your_type} (admin editor) and hdq_render_question_type_{your_type} (frontend render). NOTE: This is still very experimental and not officially supported.

hdq_add_settings_field – Add custom fields to the global HD Quiz Settings page.

hdq_add_quiz_field – Add custom fields/tabs to the quiz settings of General/Scored quizzes.

hdq_add_quiz_field_personality – Add custom fields/tabs to the quiz settings of Personality quizzes.

hdq_add_question_field – Add custom fields/tabs to the question edit screen.

hdq_content – HD Quiz’s replacement for the_content (see the “Replace the_content filter” setting). If you build addons that output rich content within quizzes, run it through this filter.