@tanstack/react-router

Modern and scalable routing for React applications

weekly downloads1.9M

versionv1.161.1

licenseMIT

categorymeta-framework

reactlocationrouterroutingasyncasync routertypescript

Overview

@tanstack/react-router is a routing library built for modern React applications that prioritizes type safety and developer experience. Unlike traditional React routers that treat routes as strings, TanStack Router makes your entire routing layer fully type-checked, including paths, parameters, search queries, and loader data. This means routing errors are caught at compile time rather than discovered by users in production.

The library was created to address limitations in existing routing solutions, particularly around type safety and data fetching patterns. It combines declarative route definitions with built-in data loaders that fetch before rendering, similar to server-side frameworks like Remix, while maintaining full client-side flexibility. The router integrates seamlessly with TanStack Query for advanced caching strategies and supports both code-based and file-based routing configurations.

With over 1.9 million weekly downloads, TanStack Router is gaining adoption among teams building complex single-page applications, dashboards, and full-stack React applications. It's particularly popular with TypeScript users who want exhaustive type checking and teams migrating from Next.js or Remix to more flexible client-side architectures. The library supports SSR, React Server Components, and provides developer tools for debugging route state and data loading.

Quick Start

typescript

import { createRootRoute, createRoute, createRouter, RouterProvider, Link, useLoaderData } from '@tanstack/react-router';
import { z } from 'zod';

const rootRoute = createRootRoute({
  component: () => (
    <div>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/posts">Posts</Link>
      </nav>
      <hr />
      <Outlet />
    </div>
  ),
});

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
  component: () => <h1>Welcome Home</h1>,
});

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'posts',
  validateSearch: z.object({
    page: z.number().default(1),
    filter: z.string().optional(),
  }),
  loader: async ({ context, search }) => {
    const response = await fetch(
      `https://jsonplaceholder.typicode.com/posts?_page=${search.page}&_limit=10`
    );
    return response.json();
  },
  component: PostsList,
});

function PostsList() {
  const posts = useLoaderData({ from: '/posts' });
  const { page, filter } = postsRoute.useSearch();
  const navigate = postsRoute.useNavigate();

  return (
    <div>
      <h2>Posts (Page {page})</h2>
      <input
        type="text"
        value={filter || ''}
        onChange={(e) => navigate({ search: { page, filter: e.target.value } })}
        placeholder="Filter posts"
      />
      <ul>
        {posts.map((post: any) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
      <button onClick={() => navigate({ search: { page: page - 1, filter } })} disabled={page === 1}>
        Previous
      </button>
      <button onClick={() => navigate({ search: { page: page + 1, filter } })}>
        Next
      </button>
    </div>
  );
}

const routeTree = rootRoute.addChildren([indexRoute, postsRoute]);
const router = createRouter({ routeTree });

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router;
  }
}

export default function App() {
  return <RouterProvider router={router} />;
}

Use Cases

Type-Safe SPA Dashboards: Build admin panels or analytics dashboards where routes have complex query parameters (filters, date ranges, pagination) that need validation and type safety. The router ensures URL state stays consistent and components receive correctly typed search params.

Multi-Tenant Applications: Create applications where routes depend on tenant context, with loaders fetching tenant-specific data before rendering. Nested routes can inherit parent loaders, avoiding duplicate data fetching across pages.

Form-Heavy Applications: Build applications with multi-step forms or wizards where URL search parameters store form state. Type-safe search params replace local state management and enable shareable URLs that restore exact form states.

Migration from Next.js to Client-Side: Teams moving away from Next.js but wanting to keep layout nesting and loader patterns can use TanStack Router to maintain similar DX while gaining more control over client-side routing and rendering.

Documentation Sites with Deep Nesting: Create documentation or content sites with deeply nested route hierarchies, where parent layouts persist across navigation and data loaders efficiently fetch content based on route parameters.

Pros & Cons

Pros

+Complete TypeScript type safety for routes, params, and search queries with compile-time validation
+Built-in data loaders with caching eliminate useEffect data fetching patterns and race conditions
+Advanced search parameter handling with validation, serialization, and schema inheritance
+Optimized re-rendering through state selectors prevents unnecessary component updates
+Flexible architecture supports both code-based and file-based routing with automatic code splitting

Cons

−Steeper learning curve compared to React Router, especially around route tree configuration and loaders
−Smaller ecosystem and community compared to established alternatives like React Router
−Type generation can slow down development builds in very large applications with hundreds of routes
−File-based routing requires specific bundler plugins (Vite, Webpack) which adds configuration complexity
−Breaking changes between versions as the library is still evolving toward a stable 2.0 release

Alternatives

nextv16.1.6

The React Framework

meta-frameworkreactframework

25.4M / week

react-routerv7.13.0

Declarative routing for React

frontendreactrouter

23.6M / week

Comparisons

react-router-dom vs @tanstack/react-router

frontend

Install

bash

npm install @tanstack/react-router

bash

pnpm add @tanstack/react-router

bash

bun add @tanstack/react-router

Overview

Quick Start

typescript

import { createRootRoute, createRoute, createRouter, RouterProvider, Link, useLoaderData } from '@tanstack/react-router';
import { z } from 'zod';

const rootRoute = createRootRoute({
  component: () => (
    <div>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/posts">Posts</Link>
      </nav>
      <hr />
      <Outlet />
    </div>
  ),
});

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
  component: () => <h1>Welcome Home</h1>,
});

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'posts',
  validateSearch: z.object({
    page: z.number().default(1),
    filter: z.string().optional(),
  }),
  loader: async ({ context, search }) => {
    const response = await fetch(
      `https://jsonplaceholder.typicode.com/posts?_page=${search.page}&_limit=10`
    );
    return response.json();
  },
  component: PostsList,
});

function PostsList() {
  const posts = useLoaderData({ from: '/posts' });
  const { page, filter } = postsRoute.useSearch();
  const navigate = postsRoute.useNavigate();

  return (
    <div>
      <h2>Posts (Page {page})</h2>
      <input
        type="text"
        value={filter || ''}
        onChange={(e) => navigate({ search: { page, filter: e.target.value } })}
        placeholder="Filter posts"
      />
      <ul>
        {posts.map((post: any) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
      <button onClick={() => navigate({ search: { page: page - 1, filter } })} disabled={page === 1}>
        Previous
      </button>
      <button onClick={() => navigate({ search: { page: page + 1, filter } })}>
        Next
      </button>
    </div>
  );
}

const routeTree = rootRoute.addChildren([indexRoute, postsRoute]);
const router = createRouter({ routeTree });

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router;
  }
}

export default function App() {
  return <RouterProvider router={router} />;
}

Use Cases

Pros & Cons

Pros

+Complete TypeScript type safety for routes, params, and search queries with compile-time validation
+Built-in data loaders with caching eliminate useEffect data fetching patterns and race conditions
+Advanced search parameter handling with validation, serialization, and schema inheritance
+Optimized re-rendering through state selectors prevents unnecessary component updates
+Flexible architecture supports both code-based and file-based routing with automatic code splitting

Cons

−Steeper learning curve compared to React Router, especially around route tree configuration and loaders
−Smaller ecosystem and community compared to established alternatives like React Router
−Type generation can slow down development builds in very large applications with hundreds of routes
−File-based routing requires specific bundler plugins (Vite, Webpack) which adds configuration complexity
−Breaking changes between versions as the library is still evolving toward a stable 2.0 release