Skip to main content
Version: 3.xx.xx

Router Provider

refine needs some router functions to create resource pages, navigate, etc. This provider allows you to use the router library you want.

A router provider must include the following methods:

const routerProvider = {
useHistory: () => {
push: (...args) => any,
replace: (...args) => any,
goBack: (...args) => any,
useLocation: () => {
pathname: string,
search: string,
useParams: <Params extends { [K in keyof Params]?: string } = {}>() => Params,
Prompt: React.FC<PromptProps*>,
Link: React.FC<any>,
RouterComponent?: React.FC<any>,

*: Too see β†’ <PromptProps>


refine includes many out-of-the-box router providers to use in your projects like


We do not recommend creating this provider unless you do not need any customization on the router. Instead, you can use Next.js Router for your Next.js app and React Router V6, React Router V5 or React Location for your react app.


To activate router provider in refine, we have to pass the routerProvider to the <Refine /> component.

import { Refine } from "@pankod/refine-core";
import routerProvider from "@pankod/refine-react-router-v6";

const App: React.FC = () => {
return <Refine routerProvider={routerProvider} />;

Creating a router provider

The routerProvider methods refine expects are exactly the same as React Router V6 methods.

To understand how to create a routerProvider, let's examine how the React Router V6, React Router V5, React Location and Next.js Router libraries provided by refine create a routerProvider.


refine uses push, replace, and goBack functions of useHistory for navigation.

import { IRouterProvider } from "@pankod/refine-core";

const routerProvider: IRouterProvider = {
useHistory: () => {
const navigate = useNavigate();

return {
push: navigate,
replace: (path: string) => {
navigate(path, { replace: true });
goBack: () => {



refine uses the pathname to find the location of the user and search to find the query string.

import { IRouterProvider } from "@pankod/refine-core";
import { useLocation } from "react-router-dom";

const routerProvider: IRouterProvider = {


refine uses useParams to use action name, record id, etc. found in the route.

import { IRouterProvider } from "@pankod/refine-core";
import { useParams } from "react-router-dom";

const routerProvider: IRouterProvider = {


refine uses <Prompt> to display the alert when warnWhenUnsavedChanges is true.

import { useEffect, useContext } from "react";
import { UNSAFE_NavigationContext as NavigationContext } from "react-router-dom";
import type { History } from "history";

import type { PromptProps } from "@pankod/refine-core";

export const Prompt: React.FC<PromptProps> = ({
}) => {
const navigator = useContext(NavigationContext).navigator as History;

useEffect(() => {
if (!when) return;

const unblock = navigator.block((transition: any) => {
if (window.confirm(message)) {
} else {
navigator.location.pathname = window.location.pathname;
return unblock;
}, [when, location, message]);

return null;
import { IRouterProvider } from "@pankod/refine-core";

import { Prompt } from "./prompt";

const routerProvider: IRouterProvider = {

refine uses <Link> for navigation.

import { IRouterProvider } from "@pankod/refine-core";
import { Link } from "react-router-dom";

const routerProvider: IRouterProvider = {


routes allow us to create custom pages in your react apps that have different paths than those defined by resources.

Refer to the Custom Pages documentation for detailed information. β†’


Since Nextjs has a file system based router built on the page concept, you can create your custom pages under the pages folder you don't need routes property.


It creates the navigation routes of the refine app and determines how the components will be rendered on which paths.

In general, we can list what it does as follows:

  • It creates create, edit, list, show pages with paths according to the resources' own name.
  • Allows rendering of custom routes passed to routerProviders as properties.
  • Different routes render when the user is authenticated and not.

RouterComponent is required for refine React apps but not required for Nextjs apps.

Since Nextjs has a folder base route structure, it is used by exporting the <NextRouteComponent> from the created page.

β†’ Refer to the React Router V6's <RouterComponent> for detailed usage information.
β†’ Refer to the React Router V5's <RouterComponent> for detailed usage information.
β†’ Refer to the React Location's <RouterComponent> for detailed usage information.
β†’ Refer to the Next.js Router's <NextRouteComponent> for detailed usage information.

Serving the application from a subdirectory

If you want to serve from a subdirectory in your refine react app. You can use basepath property of <Router>.

The <RouterComponent> in the react-router-v6 package passes all its properties to the <BrowserRouter> component. Therefore, a <BrowserRouter> property that we will give to the <RouterComponent> is passed to the <BrowserRouter> that wraps our application.

In the example below you can see how to serve the application in a subdirectory.

import { Refine } from "@pankod/refine-core";
import routerProvider from "@pankod/refine-react-router-v6";
import dataProvider from "@pankod/refine-simple-rest";
import "@pankod/refine/dist/styles.min.css";

import { PostList, PostCreate, PostEdit, PostShow } from "pages/posts";

const API_URL = "";

const { RouterComponent } = routerProvider;

const CustomRouterComponent = () => <RouterComponent basename="/admin" />;

const App: React.FC = () => {
return (
RouterComponent: CustomRouterComponent,
name: "posts",
list: PostList,
create: PostCreate,
edit: PostEdit,
show: PostShow,

export default App;

Now you can access our application at