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

​
Installation

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: 
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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us