# Path widget

> A guided journey of steps and sub-steps, rendered as a straight column, a zigzag quest, or a horizontal stepper.

Source: https://docs.hatched.live/docs/reference/widgets/path

## Mount

```html
<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

| Attribute        | Values                                          | Default  |
| ---------------- | ----------------------------------------------- | -------- |
| `data-path-key`  | A specific path definition key                  | optional |

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.