Path widget

Mount

<script
  src="https://cdn.hatched.live/widget.js"
  data-embed-token="EMBED_OR_SESSION_TOKEN"
  defer
></script>

<!-- Renders the audience's active path automatically. -->
<div data-hatched-mount="path"></div>

<!-- Or pin a specific path by key. -->
<div data-hatched-mount="path" data-path-key="buyer_onboarding"></div>

The loader mounts every data-hatched-mount="path" element. Each mount hits /widget/path[/<key>] once on init and never re-fetches — further state updates ride on effects.path_updates after track() round-trips.

Mount attributes

When data-path-key is omitted, the server returns the audience's currently-active path. When set, the widget renders that path even if it is no longer active — useful for previewing a draft.

Display modes

The widget renders either layout based on the definition's display_mode field. Operators flip the mode from the dashboard; the host page does not pick.

• straight (Straight column) — readable vertical path with a continuous accent connector. Tap a node to expand its sub-steps inline.
• zigzag (Zigzag quest) — alternating nodes and labels, Duolingo-style. Tap a node to expand its sub-steps inline.
• stepper (Compact stepper) — horizontal scrolling chip row with the active step's sub-steps expanded inline below.

Path icon

The definition's icon field renders optional decoration next to the path label. Allowed values are path, flame, heart, bolt, star, and leaf; path means no icon. The API rejects other values.

Sub-step CTAs

Each sub-step can render up to two interactive elements:

• An external link, when content_url is set, labelled with cta_label (or "Open" by default). Opens in a new tab.
• A "Mark complete" button, when allow_manual_complete: true and the current token has the events:track scope. Embed-token mounts (read-only) hide the button.

Sub-steps with neither will be rendered as a labelled list item with no actions — operators usually pair content_url with manual completion or with an automatic completion_condition.

Required scopes

• read — to load the path payload.
• events:track — only if the page wants the manual-complete CTA. Embed tokens with read only still render the path; the CTA is silently hidden.

Empty state

When the audience has no active path, the widget renders "No active path yet" instead of spinning. Embedders can use this to verify the mount worked even before the operator activates a path.

If data-path-key points to a path that does not exist for the buddy's audience, the API returns 404 and the widget renders the error state.

Theming

The widget honours the customer brand theme by default. To override the accent for a specific path, set accent_color on the definition — the widget exposes it as --hw-path-accent. The eight-axis personality system from the workspace theme (surface, geometry, motion profile, …) is forwarded as data-* attributes on the size wrapper.