## Navigating the Stripe Dashboard with Route Descriptors

This section details how to implement soft, context-preserving navigation within your Stripe App using route descriptors. This allows users to move between Dashboard pages without triggering a full page reload, maintaining their active session state.

### Key Concepts

*   **Route Descriptors:** JavaScript objects that identify a specific Dashboard page by name and optionally by resource parameters.
*   **Soft Navigation:** A client-side navigation that updates the Dashboard URL and renders the target page without a full page reload. This preserves the active context (mode, account, merchant session state).
*   **Hard Reload:** A traditional page reload that resets the active context.

### Benefits of Route Descriptors

*   **Preserves Active Context:** Maintains the user's current session state (test/live mode, active account, etc.).
*   **Type-Safe Parameters:** Ensures that parameters passed for navigation are correctly formatted.
*   **Works Across Test/Live Mode:** Seamlessly functions in both testing and live environments.

### Usage

Route descriptors require SDK version 9.2.0 or later. Ensure your SDK is updated by running:

```bash
npm install @stripe/ui-extension-sdk@latest
```

When navigating, pass a route descriptor instead of a bare `href` string to trigger a soft navigation.

### Example

The following demonstrates the difference between a hard reload using a plain `href` string and a soft navigation using a route descriptor:

| `href` String (Hard Reload) | Route Descriptor (Soft Navigation) |
| :-------------------------- | :--------------------------------- |
| Navigation Type: Hard reload | Navigation Type: Soft (client-side) |
| Preserves active context: No | Preserves active context: Yes      |
| Type-safe params: No        | Type-safe params: Yes              |
| Works across test/live mode: Yes | Works across test/live mode: Yes   |