Skip to main content
Version: 4.xx.xx

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 it is recommended to use it 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; }>;
};
info

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

tip

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.

App.tsx
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>
    );
};

Creating a router provider​

The routerProvidermethods 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 for your needs.

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. It also accepts query, hash, and options parameters to customize the navigation. The type parameter is used to specify the type of navigation. It can be 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.

to parameter is undefined. In this case, we expect go function to use the current path and add the query and hash parameters to it.

query is passed as an object to let the router library handle the query string. In our implementations, we use qs library to stringify the query object which supports nested objects. The query is also parsed in the parse method of the routerProvider, this 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 of the page.

params is an object that contains both the URL parameters and the query parameters. We use 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.

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