Configuration Reference#

Config object#

When creating a Guidestar programmatically or via the data-guidestar-config attribute, the following properties are supported:

Property	Type	Default	Description
`htmlSrc`	string	`null`	URL of the HTML file to fetch and inject into the container.
`steps`	array	`[]`	Array of step objects or shorthand strings (see below). When empty, the demo renders in static mode — no playback controls, timeline, or autostart (see Static render mode).
`initSteps`	array	`[]`	Steps executed synchronously before playback begins (or before the static render is shown). Init steps run with no delay, no highlight animation, and no cursor movement — they are intended to set up the initial DOM state. Each object supports the non-time-based fields from the step format: `target`, `action` / `actions`, `value`, `noHighlight`, `caption`, and `captionOptions`. The `delay` field is accepted but ignored. In static mode the cursor (if enabled) is placed at the last init step’s target element, and the last caption persists as a static overlay.
`repeat`	bool	`true`	Whether to loop the demo when it reaches the end.
`autoStart`	bool	`true`	Start automatically when the container is visible in the viewport.
`pauseOnInteraction`	bool	`true`	Pause the demo when the user clicks inside the container.
`cursor`	bool	`true`	Show an animated cursor that moves to each target element before the action executes. Set to `false` to disable.
`cursorSpeed`	number	`300`	Duration in milliseconds for the cursor movement animation.
`timeline`	bool	`true`	Show an interactive progress timeline at the bottom of the container on hover. Each step is represented as a dot; filled dots indicate completed steps. Click a dot to jump to that step. Set to `false` to disable (also skips HTML snapshot caching used for backward navigation).
`reduceMotion`	bool / string	`'auto'`	Controls reduced-motion behaviour. `'auto'` (default) honours the operating system’s `prefers-reduced-motion` setting. `true` forces all animations off regardless of OS preference. `false` keeps animations on even when the OS requests reduced motion. See Accessibility for details.
`onStepStart`	function	`null`	Callback `(stepIndex, step)` called before each step executes.
`onStepEnd`	function	`null`	Callback `(stepIndex, step)` called after each step executes.
`onComplete`	function	`null`	Callback called when the sequence finishes (before repeat loop).

Step format#

Steps can be provided as JSON objects or shorthand strings.

JSON object format#

{
  "target": "#my-element",
  "action": "click",
  "delay": 1500,
  "value": null,
  "noHighlight": false,
  "caption": "Click the element",
  "captionOptions": { "position": "bottom" }
}

Field	Required	Description
`target`	no	CSS selector for the target element (inside the injected HTML). Omit for `pause` actions.
`action`	yes	Action name (see table below).
`delay`	no	Milliseconds to hold on this step before advancing (default `2000`).
`value`	no	Action-specific value (e.g. class name for `toggle-class`).
`noHighlight`	no	If `true`, skip the highlight animation on this step.
`caption`	no	Text to display as a semi-transparent caption overlay during this step.
`captionOptions`	no	Object with optional keys: `position` (`"top"`, `"bottom"`, or `"auto"`; default `"auto"`) and `className` (extra CSS class to apply to the caption element for this step).

Multi-action steps#

A step can execute multiple actions at once by providing an actions array instead of a single action field. By default sub-actions run synchronously (no delay between them), and the step’s delay applies after all actions have executed.

This is useful when several DOM changes should appear simultaneously — for example, updating an image and its legend in the same visual beat, or toggling a class while also setting text.

{
  "actions": [
    { "target": "#sidebar", "action": "toggle-class", "value": "open" },
    { "target": "#status", "action": "set-text", "value": "Ready" }
  ],
  "delay": 1500,
  "caption": "Open sidebar and update status"
}

Individual sub-actions can include an optional delay (in ms) to pause before the next sub-action executes. This is useful for showing cause and effect within a single step — for example, clicking a button and then revealing the result after a short pause:

{
  "actions": [
    { "action": "click-button", "value": "Load", "delay": 500 },
    { "action": "viewer-add", "value": "horiz:Image" },
    { "action": "viewer-image", "value": "Image:photo.png" }
  ],
  "delay": 3000,
  "caption": "Load the data"
}

Sub-action delays do not create individual timeline dots, captions, or steppable positions — they are purely visual timing within one step. The delay on the last sub-action is also respected before the step’s top-level delay begins.

Each object in the actions array supports:

Field	Required	Description
`target`	no	CSS selector for the sub-action’s target element.
`action`	yes	Action name (same set as single-action steps).
`value`	no	Action-specific value.
`delay`	no	Milliseconds to wait after this sub-action before executing the next one. Defaults to `0` (immediate). Respects the current playback speed.

The top-level delay, caption, captionOptions, and noHighlight fields work the same as on a single-action step. The cursor (if enabled) moves to the first sub-action’s target element.

Shorthand string format#

target@delay:action=value|caption text

Examples:

#btn@1500:click                    → click #btn, hold 1500ms
#panel@1000:toggle-class=open      → toggle “open” class, hold 1000ms
#btn@1500!:click                   → click (no highlight), hold 1500ms
pause@3000                         → wait 3 seconds
#el:highlight                      → highlight with default 2000ms delay
#input@1000:set-value=Hello        → set input value to “Hello”   #input@1500:type-text=Hello World   → type "Hello World" letter-by-letter   #btn@1500:click|Click me           → click with auto-positioned caption
#btn@1500:click|^Click me          → click with caption forced to top
#btn@1500:click|vClick me          → click with caption forced to bottom

Caption text follows the | pipe character at the end of the string. Prefix the caption with ^ to force it to the top of the container, or v to force it to the bottom. Without a prefix, the position is chosen automatically (opposite the target element’s vertical position).

Supported actions#

Action	Value	Description
`click`	—	Simulate a click on the target element.
`add-class`	class name(s)	Add one or more CSS classes (space-separated).
`remove-class`	class name(s)	Remove one or more CSS classes.
`toggle-class`	class name(s)	Toggle one or more CSS classes.
`set-attribute`	`name:value`	Set an HTML attribute. Use colon to separate name and value.
`remove-attribute`	attr name	Remove an HTML attribute.
`set-value`	value	Set `.value` on an input/select and dispatch `input`/`change` events.
`type-text`	text	Animate typing text into an input or element over the step’s delay. Automatically uses letter-at-a-time for short text or word-at-a-time for long text, based on what yields a comfortable typing speed.
`set-text`	text	Set `.textContent` of the target.
`set-html`	html	Set `.innerHTML` of the target. Use with caution.
`scroll-into-view`	—	Smoothly scroll the target into view.
`dispatch-event`	`eventName` or `eventName:detailJSON`	Dispatch a `CustomEvent` on the target.
`highlight`	—	Temporarily highlight the target (default action when no action is specified).
`pause`	—	Wait for the step’s delay without performing any action.

Custom actions#

Packages can register their own domain-specific actions:

Guidestar.registerAction('select-tab', function(step, el, contentRoot) {
    // "this" is the Guidestar instance
    var tabs = contentRoot.querySelectorAll('.tab');
    tabs.forEach(function(tab) {
        tab.classList.remove('active');
        if (tab.textContent.trim() === step.value) {
            tab.classList.add('active');
        }
    });
});

The handler receives:

step — the full step object
el — the resolved target element (may be null)
contentRoot — the container element holding the injected HTML
this — the Guidestar instance (access this.pause(), this.play(), etc.)

Captions (transcript overlay)#

Each step can optionally display a caption — a semi-transparent text overlay that appears at the top or bottom of the demo container, similar to closed captions on a video. Captions are useful for narrating a demo walkthrough.

Adding captions#

Shorthand syntax — append |text to any step string:

#btn-sidebar@1800:click|Open the sidebar
pause@2000|Wait for the animation to finish

To force the caption position, prefix the text with ^ (top) or v (bottom):

#btn-sidebar@1800:click|^This caption appears at the top
#status-bar@1000:highlight|vThis caption appears at the bottom

JSON object syntax — use the caption and captionOptions fields:

{
  "target": "#input-search",
  "action": "type-text",
  "value": "pipeline",
  "delay": 1500,
  "caption": "Search for a pipeline",
  "captionOptions": {
    "position": "top",
    "className": "my-custom-caption"
  }
}

captionOptions fields:

Key	Description
`position`	`"top"`, `"bottom"`, or `"auto"` (default). When `"auto"`, the caption is placed opposite the target element — if the target is in the top half of the container the caption appears at the bottom, and vice versa. Steps without a target (e.g. `pause`) default to the bottom.
`className`	An extra CSS class applied to the caption element for this step, allowing per-step styling.

Steps without a caption (or with an empty string) will hide any previously visible caption.

Styling captions#

Caption appearance is controlled via CSS custom properties set on the [data-guidestar] container:

Property	What it controls	Default
`--gs-caption-bg`	Background color	`rgba(0,0,0,0.72)`
`--gs-caption-color`	Text color	`#fff`
`--gs-caption-font-size`	Font size	`14px`
`--gs-caption-padding`	Padding	`10px 16px`
`--gs-caption-inset`	Left & right inset — centres the caption and keeps it clear of the control button	`68px`

Example:

[data-guidestar] {
    --gs-caption-bg: rgba(0, 0, 80, 0.85);
    --gs-caption-font-size: 16px;
    --gs-caption-padding: 12px 20px;
}

Static render mode#

When no steps are provided, the demo operates in static render mode. The playback controls, timeline, and restart overlay are not created, and autostart is skipped. The wireframe is simply shown at whatever state initSteps leaves it in.

This is useful when you want to show a screenshot-like view of the wireframe at a specific state — for example, with a sidebar open, a field filled in, or a cursor resting over a particular element.

Setting the visual state#

Use initSteps to drive the wireframe into the desired state. All normal actions (add-class, set-value, click, etc.) are supported; time- based fields (delay) are ignored.

{
  "initSteps": [
    { "target": "#sidebar", "action": "add-class", "value": "open" },
    { "target": "#search-input", "action": "set-value", "value": "jwst" }
  ]
}

Cursor placement#

When cursor is true (the default), the cursor is placed at the centre of the last init step that has a target. Set cursor to false to hide the cursor entirely.

{
  "initSteps": [
    { "target": "#sidebar", "action": "add-class", "value": "open" },
    { "target": "#search-input", "action": "set-value", "value": "jwst",
      "caption": "Search pre-filled with a query" }
  ]
}

The cursor rests on #search-input because it is the last targeted step.

Persistent caption#

A caption on the last init step persists as a static overlay. Use captionOptions to control position as normal.

Directive example#

.. guidestar-demo:: _static/app.html
   :init-steps-json:
      [
        {"target": "#sidebar", "action": "add-class", "value": "open"},
        {"target": "#run-btn",
         "caption": "Ready to run",
         "captionOptions": {"position": "bottom"}}
      ]
   :height: 420px

This renders a static wireframe with the sidebar open, the cursor resting on #run-btn, and a caption at the bottom.

To hide the cursor:

.. guidestar-demo:: _static/app.html
   :init-steps-json: [{"target": "#sidebar", "action": "add-class", "value": "open"}]
   :cursor: false
   :height: 420px