TanStack Router Integration

React-admin supports TanStack Router as an alternative to react-router. This allows you to use react-admin in a TanStack Start application.

Installation

To use TanStack Router with react-admin, install the required packages:

npm install ra-router-tanstack @tanstack/react-router @tanstack/history
# or
yarn add ra-router-tanstack @tanstack/react-router @tanstack/history

Configuration

To use TanStack Router, set the <Admin routerProvider> to tanStackRouterProvider:

import { Admin, Resource, ListGuesser } from 'react-admin';
import { tanStackRouterProvider } from 'ra-router-tanstack';
import { dataProvider } from './dataProvider';

const App = () => (
    <Admin
        dataProvider={dataProvider}
        routerProvider={tanStackRouterProvider}
    >
        <Resource name="posts" list={ListGuesser} />
        <Resource name="comments" list={ListGuesser} />
    </Admin>
);

export default App;

That’s it! React-admin will now use TanStack Router for all routing operations.

Standalone Mode

When using tanStackRouterProvider without an existing TanStack Router, react-admin creates its own router automatically. This is called standalone mode.

In standalone mode, react-admin:

Creates a TanStack Router with hash-based history (URLs like /#/posts)
Handles all route matching internally
Manages navigation and history

This is the simplest setup and requires no additional configuration.

// Standalone mode - react-admin creates the router
import { Admin, Resource } from 'react-admin';
import { tanStackRouterProvider } from 'ra-router-tanstack';

const App = () => (
    <Admin
        dataProvider={dataProvider}
        routerProvider={tanStackRouterProvider}
    >
        <Resource name="posts" list={PostList} />
    </Admin>
);

Embedded Mode

If your application already uses TanStack Router, you can embed react-admin inside it. React-admin detects the existing router context and uses it instead of creating its own.

import * as React from 'react';
import {
    createRouter,
    createRootRoute,
    createRoute,
    RouterProvider,
    Outlet,
    Link,
} from '@tanstack/react-router';
import { createHashHistory } from '@tanstack/history';
import { Admin, Resource } from 'react-admin';
import { tanStackRouterProvider } from 'ra-router-tanstack';
import { dataProvider } from './dataProvider';
import { PostList, PostEdit } from './posts';

// Define your routes
const rootRoute = createRootRoute({
    component: () => (
        <div>
            <nav>
                <Link to="/">Home</Link>
                <Link to="/admin">Admin</Link>
            </nav>
            <Outlet />
        </div>
    ),
});

const homeRoute = createRoute({
    getParentRoute: () => rootRoute,
    path: '/',
    component: () => <div>Welcome to my app!</div>,
});

// Mount react-admin at /admin
const adminRoute = createRoute({
    getParentRoute: () => rootRoute,
    path: '/admin',
    component: () => (
        <Admin
            dataProvider={dataProvider}
            routerProvider={tanStackRouterProvider}
            basename="/admin"
        >
            <Resource name="posts" list={PostList} edit={PostEdit} />
        </Admin>
    ),
});

const routeTree = rootRoute.addChildren([homeRoute, adminRoute]);

const router = createRouter({
    routeTree,
    history: createHashHistory(),
});

const App = () => <RouterProvider router={router} />;

export default App;

Important: When embedding react-admin, set the basename prop to match the path where react-admin is mounted. In the example above, react-admin is mounted at /admin, so basename="/admin".

Custom Routes

You can use <CustomRoutes> to add custom pages. Use the Route component from tanStackRouterProvider to define routes:

import { Admin, Resource, CustomRoutes } from 'react-admin';
import { tanStackRouterProvider } from 'ra-router-tanstack';

const { Route } = tanStackRouterProvider;

const App = () => (
    <Admin
        dataProvider={dataProvider}
        routerProvider={tanStackRouterProvider}
    >
        <CustomRoutes>
            <Route path="/settings" element={<Settings />} />
            <Route path="/profile" element={<Profile />} />
        </CustomRoutes>
        <CustomRoutes noLayout>
            <Route path="/public" element={<PublicPage />} />
        </CustomRoutes>
        <Resource name="posts" list={PostList} />
    </Admin>
);

Using Router Hooks

When using TanStack Router, import routing hooks from react-admin instead of directly from TanStack Router:

// Recommended - router-agnostic
import { useNavigate, useLocation, useParams } from 'react-admin';

The hooks from react-admin work with both react-router and TanStack Router, making your code portable:

import { useNavigate, useLocation, useParams } from 'react-admin';

const MyComponent = () => {
    const navigate = useNavigate();
    const location = useLocation();
    const { id } = useParams();

    const handleClick = () => {
        navigate('/posts');
        // or navigate(-1) to go back
        // or navigate({ pathname: '/posts', search: '?filter=active' })
    };

    return (
        <div>
            <p>Current path: {location.pathname}</p>
            <p>Record ID: {id}</p>
            <button onClick={handleClick}>Go to Posts</button>
        </div>
    );
};

TanStack Router supports navigation blocking out of the box. The warnWhenUnsavedChanges feature in react-admin forms works automatically:

import { Edit, SimpleForm, TextInput } from 'react-admin';

const PostEdit = () => (
    <Edit>
        <SimpleForm warnWhenUnsavedChanges>
            <TextInput source="title" />
            <TextInput source="body" multiline />
        </SimpleForm>
    </Edit>
);

Unlike react-router (which requires a Data Router for blocking to work), TanStack Router always supports navigation blocking.

Linking Between Pages

Use the LinkBase component from react-admin for router-agnostic links:

import { LinkBase } from 'react-admin';

const Dashboard = () => (
    <div>
        <h1>Dashboard</h1>
        <LinkBase to="/posts">View all posts</LinkBase>
        <LinkBase to="/posts/create">Create a new post</LinkBase>
        <LinkBase to="/posts/123/show">View post #123</LinkBase>
    </div>
);

Or use useCreatePath for dynamic paths:

import { LinkBase, useCreatePath } from 'react-admin';

const Dashboard = () => {
    const createPath = useCreatePath();
    return (
        <div>
            <LinkBase to={createPath({ resource: 'posts', type: 'list' })}>
                Posts
            </LinkBase>
            <LinkBase to={createPath({ resource: 'posts', type: 'create' })}>
                Create Post
            </LinkBase>
            <LinkBase to={createPath({ resource: 'posts', type: 'show', id: 123 })}>
                Post #123
            </LinkBase>
        </div>
    );
};

Limitations

The TanStack Router adapter has some limitations compared to native TanStack Router usage:

Type Safety

TanStack Router’s main feature is compile-time type safety based on route definitions. The react-admin adapter doesn’t provide this level of type safety because react-admin generates routes dynamically from <Resource> components.

Search Params

TanStack Router treats search params as typed objects with validation. The adapter uses string-based search (?key=value) for compatibility with react-admin’s list filters.

Route Loaders

TanStack Router’s data loading features (loader, beforeLoad) are not used by the adapter. React-admin handles data loading through its own dataProvider system.

File-Based Routing

TanStack Router supports file-based routing similar to Next.js. This feature is not compatible with react-admin’s declarative <Resource> approach.