Router Provider
refine provides a simple interface from the routerProvider
prop to infer the resource from route, pass, parse and sync the query parameters and handle navigation operations. This provider and its properties are optional but recommended to get the most out of refine.
Rather than restricting and limiting our users to specific routing libraries or practices, we have designed the routerProvider
interface to communicate with the router libraries rather than managing them.
A router provider may contain the following methods:
const routerProvider: {
go?: () => ({
to?: string;
query?: Record<string, unknown>;
hash?: string;
options?: {
keepQuery?: boolean;
keepHash?: boolean;
};
type?: "push" | "replace" | "path";
}) => void | string;
back?: () => () => void;
parse?: () => () => {
resource?: IResourceItem;
id?: BaseKey;
action?: Action;
pathname?: string;
params?: {
filters?: CrudFilters;
sorters?: CrudSorting;
current?: number;
pageSize?: number;
[key: string]: any;
}
};
Link?: React.ComponentType<{ to: string; children?: React.ReactNode; }>;
};
refine includes many out-of-the-box router providers to use in your projects like
- React Router V6
- Next.js Router
- Remix Router
- React Router V5 (Only available for
legacyRouterProvider
, see below.)
You can also create your own router provider or easily customize the existing ones to suit your needs. The existing implementations are pretty simple and straightforward. Do not hesitate to check the source code of the existing router providers when creating your own.
Usage
To activate router provider in refine, we have to pass the routerProvider
to the <Refine />
component:
- React Router V6
- Next.js Router
- Remix Router
- React Router V5 (Legacy)
- React Location (Legacy)
import { Refine } from "@refinedev/core";
import routerProvider from "@refinedev/react-router-v6";
import { BrowserRouter } from "react-router-dom";
const App: React.FC = () => {
return (
<BrowserRouter>
<Refine
routerProvider={routerProvider}
/* ... */
>
{/* ... */}
</Refine>
</BrowserRouter>
);
};
import { Refine } from "@refinedev/core";
import routerProvider from "@pankod/refine-react-router";
const App: React.FC = () => {
return <Refine legacyRouterProvider={routerProvider} />;
};
import { Refine } from "@refinedev/core";
import routerProvider from "@pankod/refine-react-location";
const App: React.FC = () => {
return <Refine legacyRouterProvider={routerProvider} />;
};
import { Refine } from "@refinedev/core";
import routerProvider from "@refinedev/nextjs-router";
import { AppProps } from "next/app";
function MyApp({ Component, pageProps }: AppProps): JSX.Element {
return (
<Refine routerProvider={routerProvider}>
<Component {...pageProps} />
</Refine>
);
}
import type { MetaFunction } from "@remix-run/node";
import {
Links,
LiveReload,
Meta,
Outlet,
Scripts,
ScrollRestoration,
} from "@remix-run/react";
import { Refine } from "@refinedev/core";
import routerProvider from "@refinedev/remix-router";
export const meta: MetaFunction = () => ({
charset: "utf-8",
title: "New Remix + Refine App",
viewport: "width=device-width,initial-scale=1",
});
export default function App() {
return (
<html lang="en">
<head>
<Meta />
<Links />
</head>
<body>
<Refine routerProvider={routerProvider}>
<Outlet />
</Refine>
<ScrollRestoration />
<Scripts />
<LiveReload />
</body>
</html>
);
}
Creating a router provider
The routerProvider
methods are designed to be as simple as possible and to be compatible with any router library. refine also exports some helper functions to make it easier to create a customized routerProvider
.
go
The go
method is used to navigate to a specific page. It accepts a to
parameter, which is the path of the page to navigate to; the query
, hash
, and options
parameters to customize the navigation; and the type
parameter is used to specify the type of navigation, which can be either push
, replace
or path
.
The path
type returns the path to navigate, which can be used in links or redirects. The push
and replace
types navigate to the path.
The to
parameter is undefined
by default. In this case, we expect the go
function to use the current path and add the query
and hash
parameters to it.
The query
parameter is passed as an object to let the router library handle the query string. In our implementations, we use the qs
library to stringify the query object, which supports nested objects. The query
is also parsed in the parse
method of the routerProvider
, which allows us to implement custom ways of stringifying and parsing the queries.
back
The back
method is used to navigate back to the previous page. It has no parameters and has no return value.
parse
The parse
method is used to parse the current path and return the current resource
, id
and action
of the page as well as the pathname
and the params
.
params
is an object that contains both the URL parameters and the query parameters. We use the qs
library to parse the query string and return the query parameters as an object, but you can use any other library or implement your own way of parsing the query string.
resource
is the name of the resource that is used in the current page and also defined in the resources
prop of the <Refine />
component. This can be undefined
if there's no matching resource route.
Matching the resource route can be done with the help of the matchResourceFromRoute
function from the @refinedev/core
package.
id
is the id of the record that is used in the current page. This can be undefined
if there's no matching parameter.
action
is the name of the action that is used in the current page. This can be undefined
if there's no matching route for a resource action.
Link
The Link
component is used to create links to other pages. It accepts a to
parameter which is the path of the page to navigate to. It's meant to be used internally in UI packages and other parts of refine to complement the router library. It's not meant to be used directly in the application.
Source Code for the Existing Router Providers
Legacy Router Provider
refine's v4 release is backward compatible and supports the legacy router provider implementations until v5 comes out. The legacy router provider implementations are still available at /legacy
paths in the router provider packages. For example, the legacy router provider implementation for React Router V6 is available at @refinedev/react-router-v6/legacy
.
If you want to use a legacy router provider, you can pass them to the <Refine />
component using the legacyRouterProvider
prop.