Help

Quizzably is a live quiz app for home use. One person hosts from a laptop or tablet (often connected to a TV). Everyone else joins on their phones with a link or code. Answers sync in real time; the host controls pacing, reveals, and scoring.

There is no quiz database on the server — your quiz lives on the host device. The server only helps phones find the host and caches images during a session.

1. Create or pick a quiz — use the generator, a starter template, or a ZIP you already have.
2. Start hosting — New quiz, choose a unique quiz code, upload your ZIP (or pick a starter quiz).
3. Note your remote PIN — shown once after creation. Use it on your phone to control the quiz remotely. Do not put the PIN on the TV.
4. Open the central display on the TV or projector — shows the QR code and questions for the room.
5. Players join via Join quiz or the link on screen — name and colour only.

Quiz generator — build rounds and questions in the browser. Drafts autosave locally. Use the ? icons next to fields for tips (hover or tap). Download a ZIP when ready.

Starter templates — on the generator and New quiz screens, pick a quiz from the quizzes/ library. Edit it in the generator or host it as-is.

Edit an existing ZIP — on the generator, use "Edit existing ZIP…" to import, change content, and export again.

Custom library folder — deployers can add more ZIPs under quizzes/ and list them in manifest.json. Set QUIZZES_DIR to point at another folder. Run pnpm pack:quizzes after editing JSON sources in quizzes/sources/.

A quiz ZIP contains quiz.json plus optional images/*. Max 50 MB per ZIP, 5 MB per image.

A full reference for every type, field, and scoring mode (including multi-select limits and partial credit) ships with the project as docs/QUESTION_OPTIONS.md. When authoring JSON by hand, use that file or the generator's Copy JSON schema and Copy LLM prompt buttons.

• True / false — two large buttons.
• Single choice — pick one option (2–6 choices).
• Multi choice — select multiple answers; optional cap on how many picks, points per correct answer, or penalties for wrong picks (see docs).
• Free text — type an answer; auto-graded against acceptable answers, or host-marked.
• Ranking — drag to order; optional points for longest consecutive stretch in the right sequence (see docs).
• Numeric, picture reveal — see the docs above.
• Label image — name each picture (needs images in the ZIP).

Confidence round — players stake 1–5 points per question; correct answers add the stake, wrong answers subtract it. The host can reveal scores excluding a round for dramatic effect before showing full totals.

Host marked — you judge answers after each question before revealing results. Good for subjective or creative rounds.

Batch round — set batchQuestions: true on a round so players answer every question in that round at once; the host uses tabs to review each question when revealing. Quiz progress still counts each question separately.

Central display — fullscreen-friendly view for the room: lobby QR, questions, reveals, scoreboard. No remote PIN on this screen by default.

Host controls — same session on your phone (join with PIN at remote host) or on the laptop before switching to the TV tab. Start the quiz, advance questions, run reveals, and end the session.

Pause and resume — if the host browser closes or sleeps, the quiz pauses. Reopen the site and resume; players reconnect automatically.

End quiz — only when you are finished for good; clears server cache for that session.

When a round finishes, the host chooses what happens next — this is always at runtime, not baked into the quiz file:

• Suggested next — the next unplayed round in your quiz file order.
• Pick any round — choose from remaining rounds in a list.
• Invite a player — a random participant picks the next round on their phone.

Players see a waiting screen while the host decides.

Most hosts use two tabs: the central display on the TV and the remote host on a phone. You do not need a third "host controls" tab unless you want to steer from the laptop instead of the phone.

• Central display — TV or projector ("Open central display"). QR code and questions for the room. Display only; it mirrors what your phone (or laptop) has already pushed to the server.
• Remote host — your phone: Join → enter the remote PIN (shown when you create the quiz). This is normally how you reveal answers, score, and advance rounds. Keep this open while hosting.
• Host controls (optional) — "Open host controls on this device" on the laptop that created the quiz. Same buttons as the phone remote; use one or the other as your controller, not both at once unless you know what you are doing.

Players use the quiz join code on the QR / join page — not the remote PIN. Never put the PIN on the TV.

Questions can have a time limit (countdown on all devices). By default the host moves on when everyone has answered or time runs out.

Reveal — the host taps through: correct answer first, then each player's result one by one (builds suspense on phones).

Adjudication — for host-marked questions, mark each player correct or incorrect before reveal.

Next up — the host UI shows the following question so you can tee it up verbally.

Score updates — scores are never shown automatically. Between rounds (and at the finale) the host chooses when to reveal the leaderboard, and can show scores excluding the round that just finished for a before/after comparison.

After the finale you can view session stats and export results as JSON.

Open Join quiz, enter the code shown on the TV (not the 4-digit PIN — that is for the host only). Pick a name and colour. If your colour is taken, choose another.

If you refresh or lose connection, the app reconnects and restores your progress — you will not need to re-answer questions you already submitted.

• "This quiz isn't running yet" — the host has not started or the code is wrong. Ask the host to open the quiz again.
• "Can't reach the host" — check Wi‑Fi; the host browser must stay open. Host should refresh the central display tab.
• Images not loading — host must be online; images upload when the session starts. Very large images may fail the 5 MB limit — compress in the generator.
• Starter quizzes missing — ensure quizzes/ is deployed with the app or set QUIZZES_DIR.

Quiz content and answers stay on the host device (IndexedDB). The server holds temporary room routing and image cache until the quiz ends or times out (~12 hours without activity). No accounts required for family play.