Polls and Interactive Blocks

Polls and interactive blocks

Polls collect votes from signed-in readers. Reveals, code locks, and chat bubbles add interaction or visual structure without creating another chapter. Authors enter each item in the chapter where readers should encounter it.

Create a chapter poll

Open a new or existing content chapter and select Add Poll in the Polls section.

Each poll needs:

• a Poll Key that connects the poll settings to its position in the prose;
• a reader-facing Question;
• a voting Type;
• at least two answer options;
• one matching marker in the chapter content.

A chapter can contain up to ten polls, and each poll can contain from two through ten options.

Choose a Poll Key and place the marker

Use a short key such as ending, next_route, or best-character. A key:

• begins with a lowercase letter or number;
• uses lowercase letters, numbers, hyphens, and underscores only;
• contains no more than 40 characters;
• is unique within the chapter.

The form shows the marker for the current key. Copy it into the chapter content where the poll should appear:

The group has heard every proposal. Now it is time to choose.

{poll:next_route}

The winning route will influence a later chapter.

Every configured poll must have exactly one matching marker, and every marker must match a configured poll. A marker that is missing, repeated, or misspelled prevents the chapter from being saved.

Choose the voting type

• Single choice lets each voter select one option.
• Multiple choice lets each voter select more than one option. Max Selections can limit how many; leave it blank to allow any number of the listed options.
• Ranked choice lets each voter rank a first choice and optional backups. Results count each ballot's highest-ranked remaining choice through elimination rounds.

Choose the type before collecting votes. After the first vote, the voting type, maximum selections, options, and option order are locked so existing votes keep their meaning.

Decide when readers see results

The Results setting offers four choices:

• Always show results displays the current totals before and after voting.
• Show after voting hides totals until that reader votes.
• Show after poll closes reveals totals when voting ends.
• Only show results to chapter author and story staff keeps reader-facing totals private.

The chapter author and story staff can preview current results that are hidden from readers. Choose the visibility before publishing based on whether seeing early votes could influence later voters.

Control voting and closing

Set State to Active while readers may vote or Closed to end voting manually. Closes At can close an active poll at a chosen date and time. The form uses your account time zone.

Select Allow voters to change their vote when readers should be able to update a previous choice. Ranked-choice voters can also change their ranking. When the option is cleared, a saved vote is final.

Readers must log in to vote. A closed poll keeps its saved votes and shows results according to its Results setting.

Edit a poll after publication

Open Edit Chapter to update the poll. Before any votes, all of its settings and options can be changed or the poll can be removed.

After it receives a vote:

• options cannot be edited, added, removed, or reordered;
• the voting type and maximum selections cannot be changed;
• the poll cannot be deleted;
• the question, state, result visibility, vote-update choice, and closing date can still be managed.

Use My polls in the Library to find your active and closed polls and return to their chapters. Active polls in visible stories may also appear under Active Polls, helping readers discover open votes.

Add a simple reveal

A reveal begins with a quoted button label and ends with {endreveal}:

{reveal "Inspect the desk"}
A folded note is taped beneath the drawer.
{endreveal}

The reader initially sees an Inspect the desk button. Selecting it opens the hidden passage; selecting it again closes the passage. A simple reveal does not require an active game.

The hidden passage can contain ordinary Markdown and supported chapter syntax. Reveal blocks cannot be placed inside another reveal block.

A reveal can also set one existing game value when it opens:

{reveal "Take the key" set game:has_key = true}
You slip the brass key into your pocket.
{endreveal}

That form needs an active game. See Random Values, Rolls, Reveals, and Actions for value types, saved changes, and actions.

Add a code lock

A code lock asks the reader for an exact answer before showing its passage:

{lock "Enter the four-digit code" answer "1234"}
The safe clicks open. A map rests inside.
{endlock}

The prompt and answer must use straight quotation marks. The answer is exact and case-sensitive, including spaces. For example, Ember, ember, and ember are three different answers.

A code lock does not require an active game. It may contain formatted prose and other supported interactions, but a lock cannot be placed inside another lock.

Treat a code lock as a story puzzle, not as protection for private or sensitive information.

Add chat bubbles

Chat blocks format a messaging-style exchange. Put the opening and closing tags on their own lines:

{chat Alice}
Did you find the key?
{endchat}

{chat:right Bob}
Yes. Meet me at the gate.
{endchat}

{chat Alice} creates a left-side bubble with Alice as the speaker. {chat:right Bob} creates a right-side bubble. The speaker name is optional, and {chat:left Alice} may be used when you want to state the left side explicitly.

Markdown works inside the bubble, including emphasis and links. Chat bubbles cannot be nested. The opening tag, message, and {endchat} must remain on separate lines.

Keep literal examples visible

If the chapter is teaching readers about syntax rather than creating an interaction, put the syntax in backticks or a fenced example. Otherwise CHYOA will turn a valid reveal, lock, or other tag into its reader control.

Before publishing

Save a draft and check that:

1. every poll marker matches one configured poll and appears once;
2. the poll type and options express the intended question;
3. result visibility and vote changes behave as expected;
4. the poll looks correct before voting, after voting, and after closing;
5. every reveal opens and closes without breaking its surrounding sentence;
6. every lock accepts the exact intended answer and rejects a near match;
7. chat tags are on their own lines and left/right speakers alternate as intended;
8. the story's Element Theme keeps all controls readable.

Related Guide chapters

• Write and Publish Chapters
• Formatting, Images, Links, and Tables
• Reader and Game Variables