> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# navigate

> Send the end user to a page on your own site from the web widget

`navigate` makes the web widget call the page's `onNavigate` handler with a path and query parameters, so your site can route the end user to pricing, a product, or checkout. It renders nothing in the chat and works only in the web widget. The platform never teaches this block: include the syntax in the persona or a skill context, scoped to the widget, which reports `pop` as its channel. See [Response formatting](/channels/formatting/overview).

*Verified against lua-cli 3.33.0.*

## Syntax

```text theme={null}
::: navigate
![navigate](/pathname?key=value)
:::
```

## Fields

| Field        | Required | Notes                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------- |
| `/pathname`  | Yes      | A relative path on your site.                                             |
| `?key=value` | No       | Query parameters, joined with `&`; they arrive parsed in `options.query`. |

## Example

A reply that sends the end user to the pricing page:

```text theme={null}
Here is the full pricing breakdown.

::: navigate
![navigate](/pricing?source=chat)
:::
```

The page receives it through `onNavigate`:

```js theme={null}
window.LuaPop.init({
  agentId: "agent_abc123",
  environment: "production",
  onNavigate: (pathname, options) => {
    const query = new URLSearchParams(options.query).toString();
    window.location.href = query ? `${pathname}?${query}` : pathname;
  },
});
```

The handler receives `("/pricing", { query: { source: "chat" } })`. With a router, call it instead of setting `location.href`. Because navigation is immediate, put a sentence before the block so the jump isn't a surprise.

## Where it renders

| Channel                         | Behavior                                                      |
| ------------------------------- | ------------------------------------------------------------- |
| Web widget with `onNavigate`    | Calls the handler once; nothing is shown                      |
| Web widget without `onNavigate` | Dropped; nothing happens                                      |
| Every other channel             | Raw text, so send it only when `Lua.request.channel` is `pop` |

## See also

* [Response formatting](/channels/formatting/overview) — the per-channel matrix
* [Widget configuration](/channels/web-widget/configuration#navigation) — the `onNavigate` option
* [links](/channels/formatting/links) — URLs the end user chooses to open