Styling a story's DOM elements.

The stage

The central location for most Choicelab elements is the stage: an HTML element you choose as the place where Choicelab should render scenes. As scenes play, actions will be automatically added and removed from the DOM.

Editing index.html, add the attribute data-stage to an element you want to serve as the stage:

  <div id="stage" data-stage>
    <!-- Choicelab actions will render here -->

Styling actions in the stage

Actions that render in the stage always include:

  • A data-action attribute with the corresponding action name.
  • An appear class, added immediately following their rendering in the DOM, allowing you to add transitions using CSS.
  • A clear class after the scene ends.

Below is a list of actions that appear in the stage, along with their corresponding HTML tags and the value of the data-action attribute:

Element Tag data-action
All text p, with strong and em for emphasis text
Custom span elements span.yourSpanName (child of text)
Continue button button continue
Images img image
Input buttons form, with child input buttons as button input
Video video video

Scene templates

Within the stage, you can create alternate layouts for scenes by providing templates. You add the element in your HTML, then specify it in your path files.

To create a template, include it as a child of the stage. You can use the data-default-template attribute as a fallback if a scene doesn't specify a template. You can also use the attribute data-elements to force certain Choicelab elements to render there (if the parent template is selected).

<div id="stage" data-stage>

  <div data-default-template></div>

  <div class="two-column">
    <div class="col-1" data-elements="text, input"></div>
    <div class="col-2" data-elements="image"></div>


Then, in your story, specify the template in the scene's header, using a CSS class or ID selector. Below, this scene will render in the .two-column template, with text and inputs in .col-1 and the image in .col-2:

~~ .two-column

[image src="images/door.jpg"]

On your right, you see a door. But you can't decide if you should...

> Walk through the door. [door]
> Continue down the hall. [walk]

Elements that can be specified in templates

All text text
Custom span elements .yourSpanName
Continue button continue
Images image
Input buttons input
Video video

Body classes

Choicelab adds two attributes to the document <body> tag:

  • data-choicelab-state, with a value indicating Choicelab's current playback status
  • If a saved story was restored on page load: data-choicelab-resumed


idle Choicelab is enabled, but hasn't finished loading (and isn't ready to play)
ready Choicelab is ready to play, but hasn't been started yet
playing Choicelab is playing
paused Choicelab is paused

Playback controls

Choicelab can automatically turn an HTML element into one of several playback controls. Here are a few of the controls provided, along with instructions for enabling them:

Closed captions

Pulls closed captions from audio, video, and closed caption actions.

  • data-cc-button (button), data-cc-box (text box)
  • When captions are enabled, the button includes the class captions-visible, and the text box includes the class visible.
  • If the given button element is empty, it will automatically render an icon.
<div class="captions">
  <p data-cc-box>
    <!-- Captions will render as a string here -->
<button class="controls" data-cc-button></button>

Reset button

Clears any saved data and reloads the page.

  • data-reset-button
  • If the given element is empty, the button automatically renders an icon.
<button class="controls" data-reset-button></button>

Play/pause button

Plays or pauses all audio, video, and timed elements.

  • data-play-button
  • The button includes a data-state attribute to indicate Choicelab's playback status; see Body classes, above, for a list of possible states.
  • If the given element is empty, the button automatically renders an icon.
<button class="play-pause controls" data-play-button></button>