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

# useNavigate

> Returns a navigation function for programmatic navigation within the host app.

```typescript theme={null}
useNavigate(): (options: { to: string; props?: Record<string, string> }) => void;
```

## Returns

A function that triggers navigation. The host app defines how navigation requests are handled.

<ParamField path="options" type="object" required>
  Navigation options.

  <Expandable title="options fields">
    <ParamField path="to" type="string" required>
      The navigation destination identifier. This is typically a screen name, route path, or component name defined by the host app.
    </ParamField>

    <ParamField path="props" type="Record<string, string>" optional>
      Key-value pairs passed to the destination screen as parameters.
    </ParamField>
  </Expandable>
</ParamField>

## Usage

### Navigate to a detail screen

```typescript theme={null}
const body = (props) => {
    const navigate = useNavigate()

    return Button("View Details", () => {
        navigate({ to: "DetailView", props: { id: props.itemId } })
    })
}
```

### Navigate with multiple parameters

```typescript theme={null}
const body = (props) => {
    const navigate = useNavigate()

    return Button("Open Profile", () => {
        navigate({
            to: "ProfileScreen",
            props: {
                userId: props.userId,
                tab: "settings"
            }
        })
    })
}
```

## Notes

* `useNavigate` must be called inside a component `body` function, not at the top level.
* The `to` value and how navigation is handled depends entirely on the host app's navigation setup. The BindJS runtime forwards the request to the native navigation handler.
* All prop values must be strings.

## See Also

* [useAction](/bindjs/functions/useAction) -- dispatch arbitrary actions to the host app