Navigate within the Dashboard using route descriptors
Soft, context-preserving navigation to Dashboard pages from your Stripe App.
Note
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 | ||
| Type-safe params | ||
| Works across test/live mode |
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 href prop: navigates to the destination when selected
- Button href prop: navigates to the destination when the button is selected
- navigateToDashboardRoute utility: imperative navigation
Examples
Link component
Button component
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.
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.
navigateToDashboardRoute({
name: 'fullPage',
params: {appId: 'my.app', tabId: 'details'},
envParams: {sourceViewport: 'drawer', recordId: '123'},
});
The destination view receives these values inside environment.queryParams.