> ## 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 Component
> Direct users to specific pages on your website
## Overview
The **Navigate** component lets your agent send users to a specific page on your website — pricing, a product, checkout, docs, or any path.
This component only works in the website chat widget (Lua Pop) and requires an `onNavigate` handler in your widget config.
## Format
```
::: navigate
:::
```
* `pathname` — a relative page path (e.g. `/pricing`, `/products/laptop`, `/checkout`)
* `?param=value` — optional query parameters
Navigate **renders nothing in the chat** — no button or link. When the message arrives, the widget strips the block and immediately calls your `onNavigate` handler, so navigation happens automatically. Always include a line of context before the block so the jump isn't a surprise.
## How it works
```
Our pricing starts at $300/month. Here's the full breakdown:
::: navigate
:::
```
```javascript theme={null}
onNavigate("/pricing", { query: { channel: "web" } });
```
Route the user using your framework (see below).
## Configure the onNavigate handler
Navigation only works if you pass an `onNavigate` handler to the widget. It receives the `pathname` and an options object with the parsed `query` params.
```javascript theme={null}
window.LuaPop.init({
agentId: "your-agent-id",
onNavigate: (pathname, options) => {
// pathname: "/pricing"
// options.query: { channel: "web" }
const params = new URLSearchParams(options.query).toString();
window.location.href = params ? `${pathname}?${params}` : pathname;
}
});
```
Using a router? Swap the last line for your framework:
```javascript theme={null}
// React Router
navigate({ pathname, search: new URLSearchParams(options.query).toString() });
// Next.js
router.push({ pathname, query: options.query });
// Vue Router
router.push({ path: pathname, query: options.query });
```
## Query parameters
Pass data to the destination page through the URL:
```
::: navigate
:::
```
```javascript theme={null}
onNavigate("/products/laptop", {
query: { source: "chat", campaign: "spring" }
});
```
Common uses: attribution (`?source=chat`), pre-filling forms (`?product=123`), campaigns (`?promo=SAVE10`), or opening a specific tab/filter (`?tab=specs`).
## Tell your agent to use it
Components are never used automatically — instruct the agent in its **persona** or a **skill context**:
```yaml theme={null}
persona: |
You are a shopping assistant for TechStore.
After describing a product, send the user to its page:
::: navigate
:::
For pricing questions, send them to pricing:
::: navigate
:::
Always add source=chat for tracking.
```
## Best practices
Because navigation is automatic, precede the block with a sentence about where the user is going (e.g. "Here's the full pricing breakdown:") so the jump feels intentional.
Prefer `/pricing` or `/products/123` over absolute URLs like `https://yoursite.com/pricing` — relative paths route correctly through `onNavigate`.
Add `?source=chat` (or similar) so you can measure how much traffic and conversion comes from the agent.
## Troubleshooting
Make sure an `onNavigate` handler is passed to `window.LuaPop.init()`. Without it the block is stripped but no navigation occurs. Check the console for errors and confirm the pathname is relative.
Use a single `?` and join params with `&`: `/page?a=1&b=2` (not `/page?a=1?b=2`).
The agent only uses the component if you instruct it in the persona or skill context with the exact format shown above.
## Next steps
Set up the onNavigate handler
All widget callbacks and events
Explore the other components