# Navigate within the Dashboard using route descriptors

Soft, context-preserving navigation to Dashboard pages from your Stripe App.

> Route descriptors require SDK version 9.2.0 or later. To install or upgrade, run: `npm install @stripe/ui-extension-sdk@latest`.

Route descriptors let your app navigate users to specific Dashboard pages without triggering a full page reload, keeping their active session intact. A route descriptor is a JavaScript object that identifies a Dashboard page by name and, optionally, by resource parameters. Passing a route descriptor instead of a bare `href` string triggers a *soft navigation*. The Dashboard URL updates and the target page renders without a full page reload.

## Benefits of route descriptors

|                             | Plain `href` string | Route descriptor   |
| --------------------------- | ------------------- | ------------------ |
| Navigation type             | Hard reload         | Soft (client-side) |
| Preserves active context    | - Unsupported       | ✓ Supported        |
| Type-safe params            | - Unsupported       | ✓ Supported        |
| Works across test/live mode | - Unsupported       | ✓ Supported        |

**Active context** refers to mode (test vs. live), the active account, and the current merchant session state. A hard reload resets that state; a soft navigation preserves it. This matters most when your app navigates users to related Dashboard objects — for example, from a drawer to a customer details page — because it keeps them in the session they were already in.

## Where to use route descriptors

Route descriptors are accepted wherever an `href` attribute or navigation argument is expected:

- [`Link`](https://docs.stripe.com/stripe-apps/components/link.md) `href` prop: navigates to the destination when selected
- [`Button`](https://docs.stripe.com/stripe-apps/components/button.md) `href` prop: navigates to the destination when the button is selected
- [`navigateToDashboardRoute`](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#navigateToDashboardRoute) utility: imperative navigation

## Examples

### Link component

```ts
import {Link} from '@stripe/ui-extension-sdk/ui';

function CustomerLink({customerId}: {customerId: string}) {
  return (
    <Link
      href={{
        name: 'customerDetails',
        params: {customerId},
      }}
    >
      View customer
    </Link>
  );
}
```

### Button component

```ts
import {Button} from '@stripe/ui-extension-sdk/ui';

function PaymentsButton() {
  return (
    <Button
      href={{
        name: 'payments',
      }}
    >
      Go to Payments
    </Button>
  );
}
```

### Imperative navigation with navigateToDashboardRoute

Use `navigateToDashboardRoute` when you need to navigate in response to an event (for example, after a form submission or a successful API call) rather than from a rendered link or button.

```ts
import {useCallback} from 'react';
import {Button} from '@stripe/ui-extension-sdk/ui';
import {navigateToDashboardRoute} from '@stripe/ui-extension-sdk/utils';

function App({customerId}: {customerId: string}) {
  const goToCustomer = useCallback(() => {
    navigateToDashboardRoute({
      name: 'customerDetails',
      params: {customerId},
    });
  }, [customerId]);

  return <Button onPress={goToCustomer}>View customer</Button>;
};
```

## Passing parameters to the destination view

Use the optional `envParams` field to pass custom key-value pairs to the `environment` prop of the view being navigated to. This is useful for communicating state across viewports without relying on external storage.

```ts
navigateToDashboardRoute({
  name: 'fullPage',
  params: {appId: 'my.app', tabId: 'details'},
  envParams: {sourceViewport: 'drawer', recordId: '123'},
});
```

The destination view receives these values inside `environment.objectContext`.

## See also

- [Link component](https://docs.stripe.com/stripe-apps/components/link.md)
- [Button component](https://docs.stripe.com/stripe-apps/components/button.md)
- [navigateToDashboardRoute](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#navigateToDashboardRoute)
- [FullPageView component](https://docs.stripe.com/stripe-apps/components/fullpageview.md)