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

# Page Navigation

> Let your AI agent navigate users between pages

Page Navigation enables your AI agent to navigate users to different pages in your application. Define your routes on the dashboard and the agent handles the rest — no code required.

## Setup

1. Go to [Page Navigation](https://app.usecrow.ai/tools/page-navigation) in your dashboard
2. Enable the **Page Navigation** toggle
3. Add your application's routes
4. Click **Save**

## Defining Routes

Each route has:

| Field           | Required      | Description                                                 |
| --------------- | ------------- | ----------------------------------------------------------- |
| **Name**        | Yes           | A unique identifier (e.g. `user_profile`, `dashboard`)      |
| **Path**        | Yes           | The URL path pattern (e.g. `/users/:userId`)                |
| **Description** | No            | What this page shows — helps the AI decide when to navigate |
| **Parameters**  | Auto-detected | Descriptions for dynamic URL segments                       |

### Static Routes

For pages with fixed URLs, just provide the name, path, and description:

| Name        | Path                | Description    |
| ----------- | ------------------- | -------------- |
| `dashboard` | `/dashboard`        | Main dashboard |
| `settings`  | `/settings/general` | App settings   |

### Dynamic Routes

Use `:paramName` syntax for URL segments that change. The AI fills in parameter values from conversation context.

| Name           | Path                                 | Parameters                      |
| -------------- | ------------------------------------ | ------------------------------- |
| `user_profile` | `/users/:userId`                     | `userId` — The user's unique ID |
| `order_detail` | `/orders/:orderId`                   | `orderId` — The order number    |
| `project_task` | `/projects/:projectId/tasks/:taskId` | `projectId`, `taskId`           |

## How the AI Gets Dynamic Parameters

The AI resolves parameter values from context — you don't need to hardcode IDs:

* **From conversation** — "Go to John's profile" after the user mentioned John earlier
* **From API results** — A previous tool call returned a list of users with their IDs
* **From user input** — "Navigate to order #ORD-4521"
* **From screen context** — If Screen Context is enabled, the AI can read IDs from the current page

## How Navigation Works

By default, when the AI calls `navigateToPage`, the SDK resolves the route name to a URL path and navigates using `window.location.href`. This works universally with any framework but triggers a full page load.

For **single-page applications** (React, Next.js, Vue, etc.), you can pass a `navigate` prop to use your framework's router instead — giving you instant SPA navigation with no page reloads.

## SPA Navigation

Pass your framework's router function via the `navigate` prop. The SDK handles route resolution — your function just receives the final path.

<CodeGroup>
  ```jsx React Router theme={null}
  import { useNavigate } from 'react-router-dom';
  import { CrowWidget } from '@usecrow/ui';

  function App() {
    const navigate = useNavigate();

    return (
      <CrowWidget
        productId="your-product-id"
        navigate={(path) => navigate(path)}
      />
    );
  }
  ```

  ```jsx Next.js theme={null}
  import { useRouter } from 'next/navigation';
  import { CrowCopilot } from '@usecrow/ui';

  function App() {
    const router = useRouter();

    return (
      <CrowCopilot
        productId="your-product-id"
        navigate={(path) => router.push(path)}
      />
    );
  }
  ```

  ```jsx Vue Router theme={null}
  // Pass router.push as the navigate function
  <CrowWidget
    product-id="your-product-id"
    :navigate="(path) => $router.push(path)"
  />
  ```
</CodeGroup>

<Note>
  The `navigate` prop only controls *how* navigation executes. Your route definitions on the dashboard still power the AI's awareness of what pages exist and how to resolve dynamic parameters.
</Note>

## Best Practices

* **Write clear descriptions** — "User profile page showing account details and activity" is better than "Profile"
* **Describe parameters** — Help the AI understand what values are expected (e.g. "The user's UUID from the users API")
* **Start with key pages** — Add your most-navigated pages first, expand later
* **Test in Sandbox** — Try asking the agent to navigate and verify it works before deploying

***

<CardGroup cols={2}>
  <Card title="Actions" icon="bolt" href="/actions-overview">
    Configure what your agent can do
  </Card>

  <Card title="Screen Context" icon="monitor" href="/sandbox-overview">
    Let the AI see what's on screen
  </Card>
</CardGroup>