Router Devtools

Debug and inspect your TanStack Router application with the official devtools

The TanStack Router Devtools help you visualize and debug your router’s state, routes, and navigation during development.

Installation

React

npm install @tanstack/react-router-devtools
# or
pnpm add @tanstack/react-router-devtools
# or
yarn add @tanstack/react-router-devtools

The devtools are tree-shakeable and will be automatically excluded from production builds when using process.env.NODE_ENV === 'production'.

Basic Setup

Add the devtools component to your root route or application component:

React

import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
import { createRootRoute } from '@tanstack/react-router'

export const Route = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

That’s it! The devtools will now appear in the bottom-right corner of your application.

Configuration Options

Customize the devtools appearance and behavior:

<TanStackRouterDevtools
  position="bottom-right"
  initialIsOpen={false}
  panelProps={{
    className: 'my-devtools-panel',
    style: { maxHeight: '80vh' }
  }}
  toggleButtonProps={{
    className: 'my-toggle-button'
  }}
  closeButtonProps={{
    className: 'my-close-button'
  }}
/>

Props

position · 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' · default: "bottom-left"

The position of the TanStack Router logo toggle button

initialIsOpen · boolean · default: false

Whether the devtools panel should be open by default

panelProps · HTMLAttributes<HTMLDivElement>

Props to pass to the devtools panel container. Useful for adding custom styles or className

toggleButtonProps · ButtonHTMLAttributes<HTMLButtonElement>

Props to pass to the toggle button. Can be used to customize appearance or extend onClick behavior

closeButtonProps · ButtonHTMLAttributes<HTMLButtonElement>

Props to pass to the close button inside the panel

containerElement · string | React.ComponentType · default: "footer"

The HTML element or React component to use as the container. Useful for accessibility

router · AnyRouter

Explicitly pass a router instance. If not provided, the devtools will use the router from context

shadowDOMTarget · ShadowRoot

Attach the devtools styles to a specific Shadow DOM root

Using the Devtools Panel

The Router Devtools provide several powerful features:

Route Tree View

Visualizes your entire route tree structure:

• See all routes and their relationships
• Inspect route configuration (path, params, search params)
• View which routes are currently active
• Understand route hierarchy at a glance

Active Route Inspector

Inspect the currently active route:

• View all matched routes in the current navigation
• See search params and their values
• Inspect path params
• View route context and loader data
• Check route state and pending status

Navigation History

Track your navigation history:

• See all previous navigations
• View the navigation stack
• Inspect state changes over time
• Debug navigation issues

Router State

View the entire router state:

• Current location and matches
• Pending location and matches (during navigation)
• Router options and configuration
• Cached route data

Production Builds

The devtools are automatically excluded from production builds:

import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

// In production, this renders null and is tree-shaken away
<TanStackRouterDevtools />

If you need to include the devtools in production for debugging:

import { TanStackRouterDevtoolsInProd } from '@tanstack/react-router-devtools'

// This will always render, even in production
<TanStackRouterDevtoolsInProd />

Only use TanStackRouterDevtoolsInProd for temporary debugging in production. Remove it before deploying to end users.

Standalone Panel Mode

Render the devtools panel without the toggle button:

import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'

// Render the panel inline in your layout
<TanStackRouterDevtoolsPanel />

This is useful when:

• Building custom developer tools
• Creating a dedicated debugging page
• Integrating with other devtools
• You want full control over when/where the panel appears

Custom Styling

The devtools can be styled using CSS:

<TanStackRouterDevtools
  panelProps={{
    style: {
      background: '#1a1a1a',
      color: '#fff',
      borderRadius: '8px',
    }
  }}
  toggleButtonProps={{
    style: {
      background: 'linear-gradient(to right, #06b6d4, #3b82f6)',
    }
  }}
/>

Or with CSS classes:

<TanStackRouterDevtools
  panelProps={{ className: 'custom-devtools-panel' }}
  toggleButtonProps={{ className: 'custom-toggle-button' }}
/>

Shadow DOM Integration

If your application uses Shadow DOM, attach the devtools styles:

const shadowRoot = document.getElementById('shadow-host')?.shadowRoot

<TanStackRouterDevtools shadowDOMTarget={shadowRoot} />

Best Practices

1. Add to Root Route: Place the devtools in your root route component so they’re available throughout your app

2. Development Only: Let the automatic tree-shaking handle production exclusion - don’t manually wrap in if (process.env.NODE_ENV === 'development')

3. Custom Position: Choose a position that doesn’t interfere with your app’s UI

4. Panel Props: Use panelProps to ensure the devtools integrate well with your app’s design

5. Accessibility: Use containerElement to ensure proper semantic HTML structure

Deprecated Package

The @tanstack/router-devtools package is deprecated. Use the framework-specific packages instead:

• @tanstack/react-router-devtools for React
• @tanstack/solid-router-devtools for Solid
• @tanstack/vue-router-devtools for Vue

Troubleshooting

Devtools not appearing

1. Ensure you’re in development mode (process.env.NODE_ENV !== 'production')
2. Check that the component is rendered in your tree
3. Verify no CSS is hiding the devtools

Type errors

1. Ensure your router is properly registered in TypeScript
2. Check that all route types are correctly inferred
3. Update to the latest version of TanStack Router

Performance issues

If the devtools impact performance:

1. Close the panel when not in use
2. Consider using panel mode only on a dedicated debug page
3. Report the issue on GitHub with reproduction steps