Skip to main content
Unlock powerful debugging and effortless query monitoring with Refine DevtoolsLearn More
RefineDocumentation
Version: 4.xx.xx

Routing

Routing is essential for any CRUD application. Refine's headless architecture allows you to use any router solution, without being locked into a specific router/framework.

Refine also offers built-in router integrations for the most popular frameworks such as React Router, Next.js and Remix.

These integrations makes it easier to use Refine with these frameworks and offers a lot of benefits such as:

  • Automatic parameter detection in hooks/components.
  • Automatic redirections after mutation or authentication.
  • Set of utility components & hooks which can be used to navigate between pages/routes.

Since Refine is router agnostic, you are responsible for creating your own routes.

If you are using React Router, you'll be defining your routes under the Routes component.
If you are using Next.js, you'll be defining your routes in the pages or app directory.
If you are using Remix, you'll be defining your routes in the app/routes directory.

Router Integrations​

To integrate a router provider with Refine, all you need to do is to import the router integration of your choice and pass it to the <Refine />'s routerProvider prop.

App.tsx
import { BrowserRouter, Routes } from "react-router-dom";
import routerProvider from "@refinedev/react-router-v6";

const App = () => (
  <BrowserRouter>
    <Refine routerProvider={routerProvider}>
      <Routes>{/* Your route definitions */}</Routes>
    </Refine>
  </BrowserRouter>
);

Check out React Router documentation for detailed information

Once you passed router provider to <Refine /> component, you can use all the features of Refine in a same way, regardless of your application's framework/router.

Relationship Between Resources and Routes
Check the guide
Please check the guide for more information on this topic.
​

Refine can infer current resource, action and it's id from the current route based on your resource definitions.

This eliminates the need of passing these parameters to the components/hooks manually.

All you have to do is to define your resource and their routes.

<Refine
  resources={[
    {
      name: "products",
      list: "/my-products", // http://localhost:3000/my-products
      show: "my-products/:id", // http://localhost:3000/my-products/1
      create: "/my-products/new", // http://localhost:3000/my-products/new
      edit: "/my-products/:id/edit", // http://localhost:3000/my-products/1/edit
      clone: "/my-products/:id/clone", // http://localhost:3000/my-products/1/clone
    },
  ]}
/>

You can see how we omit resource and id parameters for useList, and useShow hooks in the examples below.

React Router​

import React from "react";

import { useGo, useShow } from "@refinedev/core";

export const ProductShow: React.FC = () => {
  // We're inferring the resource and the id from the route params
  // So we can call useShow hook without any arguments.
  // const result = useShow({ resource: "products", id: "xxx" })
  const result = useShow();

  const {
    queryResult: { data, isLoading },
  } = result;

  const go = useGo();

  if (isLoading) return <div>Loading...</div>;

  return (
    <>
      <div>
        <h1>{data?.data?.name}</h1>
        <p>Material: {data?.data?.material}</p>
        <small>ID: {data?.data?.id}</small>
      </div>
      <button
        onClick={() => {
          go({
            to: {
              resource: "products",
              action: "list",
            },
          });
        }}
      >
        Go to Products list
      </button>
    </>
  );
};
Open on CodeSandboxOpen Sandbox

Next.js​

import React from "react";

import { useGo, useShow } from "@refinedev/core";

const ProductShow = () => {
  // We're inferring the resource and the id from the route params
  // So we can call useShow hook without any arguments.
  // const result = useShow({ resource: "products", id: "xxx" })
  const result = useShow();

  const {
    queryResult: { data, isLoading },
  } = result;

  const go = useGo();

  if (isLoading) return <div>Loading...</div>;

  return (
    <>
      <div>
        <h1>{data?.data?.name}</h1>
        <p>Material: {data?.data?.material}</p>
        <small>ID: {data?.data?.id}</small>
      </div>
      <button
        onClick={() => {
          go({ to: { resource: "products", action: "list" } });
        }}
      >
        Go to Products list
      </button>
    </>
  );
};

export default ProductShow;
Usage with App Router

You can see the example here: https://github.com/refinedev/refine/tree/master/examples/with-nextjs

Remix​

import React from "react";

import { useGo, useShow } from "@refinedev/core";

const ProductShow = () => {
  // We're inferring the resource and the id from the route params
  // So we can call useShow hook without any arguments.
  // const result = useShow({ resource: "products", id: "xxx" })
  const result = useShow();

  const {
    queryResult: { data, isLoading },
  } = result;

  const go = useGo();

  if (isLoading) return <div>Loading...</div>;

  return (
    <>
      <div>
        <h1>{data?.data?.name}</h1>
        <p>Material: {data?.data?.material}</p>
        <small>ID: {data?.data?.id}</small>
      </div>
      <button
        onClick={() => {
          go({ to: { resource: "products", action: "list" } });
        }}
      >
        Go to Products list
      </button>
    </>
  );
};

export default ProductShow;

Hook Integrations​

useForm
Check the guide
Please check the guide for more information on this topic.
​

Router integration of Refine allows you to use useForm without passing resource, id and action parameters. It will also redirect you to resource's action route defined in redirect prop. redirect prop is list by default.

import React from "react";

import { useForm } from "@refinedev/core";

export const ProductEdit: React.FC = () => {
  const { formLoading, onFinish, queryResult } = useForm();
  const defaultValues = queryResult?.data?.data;

  const onSubmit = (e) => {
    e.preventDefault();
    const data = Object.fromEntries(new FormData(e.target).entries());

    onFinish(data);
  };

  return (
    <div>
      <br />
      <form onSubmit={onSubmit}>
        <div>
          <label htmlFor="name">name</label>
          <input
            type="text"
            id="name"
            name="name"
            placeholder="name"
            defaultValue={defaultValues?.name}
          />
        </div>
        <button type="submit" disabled={formLoading}>
          <span>Save</span>
        </button>
      </form>
    </div>
  );
};
Open on CodeSandboxOpen Sandbox

Additionally, router integrations exposes an <UnsavedChangesNotifier /> component which can be used to notify the user about unsaved changes before navigating away from the current page. This component provides this feature which can be enabled by setting warnWhenUnsavedChanges to true in useForm hooks.

app.tsx
import { Refine } from "@refinedev/core";
import {
  routerProvider,
  UnsavedChangesNotifier,
} from "@refinedev/react-router-v6";
import { BrowserRouter, Routes } from "react-router-dom";

const App = () => (
  <BrowserRouter>
    <Refine
      // ...
      routerProvider={routerProvider}
      options={{
        warnWhenUnsavedChanges: true,
      }}
    >
      <Routes>{/* ... */}</Routes>
      {/* The `UnsavedChangesNotifier` component should be placed under <Refine /> component. */}
      <UnsavedChangesNotifier />
    </Refine>
  </BrowserRouter>
);

Check out the UnsavedChangesNotifier section of the React Router integration documentation for more information.

useTable
Check the guide
Please check the guide for more information on this topic.
​

useTable can synchronize it's parameters (filters, pagination, sorting) with the current route.

To enable synchronization, you need to pass syncWithLocation: true to <Refine /> component's options prop.

<Refine {...} options={{ syncWithLocation: true }}>

Once you pass syncWithLocation: true to <Refine /> component's options prop, useTable will:

  • Read the current route and update it's parameters (filters, pagination, sorting) accordingly.
  • Update the current route when it's parameters (filters, pagination, sorting) change.

Let's say we have a products list page with the following route:

/my-products

And we want to filter products by category.id and sort them by id in asc order.

We can pass these parameters to useTable hook as follows:

const { ... } = useTable(
    {
        current: 1,
        pageSize: 2,
        filters: { initial: [{ field: "category.id", operator: "eq", value: 1 }]},
        sorters: { initial: [{ field: "id", direction: "asc" }] }
    }
);

useTable will automatically update the route to:

http://localhost:3000/my-products
/my-products

/my-products?current=1&pageSize=2&sorters[0][field]=id&sorters[0][order]=asc&filters[0][field]=category.id&filters[0][operator]=eq&filters[0][value]=1

And you will see a list of products, already filtered, sorted and paginated automatically based on the query parameters of the current route.

const { tableQueryResult, current, pageSize, filters, sorters } = useTable();

console.log(tableQueryResult.data.data); // [{...}, {...}]
console.log(tableQueryResult.data.total); // 32 - total number of unpaginated records
console.log(current); // 1 - current page
console.log(pageSize); // 2 - page size
console.log(filters); // [{ field: "category.id", operator: "eq", value: "1" }]
console.log(sorters); // [{ field: "id", order: "asc" }]

Check the examples below to see how you can use useTable with router integration.

Notice how components/products/list.tsx is the same, regardless of the router integration.

React Router​

import React from "react";

import { useTable } from "@refinedev/core";

import { ProductList } from "../../components/products/list";

export const ListPage: React.FC = () => {
  const tableProps = useTable({
    pagination: { current: 1, pageSize: 2 },
    filters: {
      initial: [{ field: "category.id", operator: "eq", value: "1" }],
    },
    sorters: { initial: [{ field: "id", order: "asc" }] },
  });

  return <ProductList tableProps={tableProps} />;
};
Open on CodeSandboxOpen Sandbox

Next.js​

You can use SSR feature with Next.js to fetch initial data on the server side.

import React from "react";

import { useTable } from "@refinedev/core";
import { parseTableParams } from "@refinedev/nextjs-router/pages";
import dataProvider from "@refinedev/simple-rest";

import { ProductList } from "../../components/products/list";

export const getServerSideProps = async (context) => {
  const {
    pagination: queryPagination,
    filters: queryFilters,
    sorters: querySorters,
  } = parseTableParams(context.resolvedUrl?.split("?")[1] ?? "");

  const pagination = {
    current: queryPagination.current ?? 1,
    pageSize: queryPagination.pageSize ?? 2,
  };

  const filters = queryFilters ?? [
    {
      field: "category.id",
      operator: "eq",
      value: "1",
    },
  ];

  const sorters = querySorters ?? [{ field: "id", order: "asc" }];

  const data = await dataProvider("https://api.fake-rest.refine.dev").getList({
    resource: "products",
    filters,
    pagination,
    sorters,
  });

  return {
    props: {
      initialData: data,
      initialProps: { pagination, filters, sorters },
    },
  };
};

const ProductListPage = (props) => {
  const {
    initialData,
    initialProps: { filters, sorters, pagination },
  } = props;

  const tableProps = useTable({
    queryOptions: { initialData },
    filters: { initial: filters },
    sorters: { initial: sorters },
    pagination,
  });

  return <ProductList tableProps={tableProps} />;
};

export default ProductListPage;

Remix​

You can use SSR feature with Remix to fetch initial data on the server side.

import React from "react";

import { json, LoaderFunctionArgs } from "@remix-run/node";
import { useLoaderData } from "@remix-run/react";

import { useTable } from "@refinedev/core";
import { parseTableParams } from "@refinedev/remix-router";
import dataProvider from "@refinedev/simple-rest";

import { ProductList } from "../components/products/list";

export async function loader({ request }: LoaderFunctionArgs) {
  const url = new URL(request.url);

  const {
    pagination: queryPagination,
    filters: queryFilters,
    sorters: querySorters,
  } = parseTableParams(url.search);

  const pagination = {
    current: queryPagination.current ?? 1,
    pageSize: queryPagination.pageSize ?? 2,
  };

  const filters = queryFilters ?? [
    {
      field: "category.id",
      operator: "eq",
      value: "1",
    },
  ];

  const sorters = querySorters ?? [{ field: "id", order: "asc" }];

  const data = await dataProvider("https://api.fake-rest.refine.dev").getList({
    resource: "products",
    filters,
    pagination,
    sorters,
  });

  return json({
    initialData: data,
    initialProps: { pagination, filters, sorters },
  });
}

const ProductList = () => {
  const {
    initialData,
    initialProps: { filters, sorters, pagination },
  } = useLoaderData<typeof loader>();
  const tableProps = useTable({
    queryOptions: { initialData },
    filters: { initial: filters },
    sorters: { initial: sorters },
    pagination,
  });

  return <ProductList tableProps={tableProps} />;
};

export default ProductList;

useModalForm​

useModalForm can automatically detect resource parameter from the current route.

It can also sync it's parameters with the current route.

const { ... } = useModalForm({ syncWithLocation: true })

Once the modal is visible, current route will look like this:

/my-products?modal-products-edit[open]=true&modal-products-edit[id]=1

You can see the example below for usage.

import React from "react";

import { useList } from "@refinedev/core";
import { useModalForm } from "@refinedev/react-hook-form";

import { Modal } from "../../components/modal.tsx";

export const ProductList: React.FC = () => {
  const { data, isLoading } = useList();

  const {
    modal: { visible, close, show },
    refineCore: { onFinish, formLoading },
    handleSubmit,
    register,
    saveButtonProps,
  } = useModalForm({
    refineCoreProps: { action: "edit" },
    syncWithLocation: true,
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <>
      <Modal isOpen={visible} onClose={close}>
        <form onSubmit={handleSubmit(onFinish)}>
          <div>
            <label htmlFor="name">name</label>
            <input {...register("name")} />
          </div>
          <button type="submit" {...saveButtonProps}>
            <span>Save</span>
          </button>
        </form>
      </Modal>
      <ul>
        {data?.data?.map((product) => (
          <li key={product.id}>
            <span>{product.name}</span>
            <button
              onClick={() => {
                show(product.id);
              }}
            >
              edit
            </button>
          </li>
        ))}
      </ul>
    </>
  );
};
Open on CodeSandboxOpen Sandbox

useOne​

useOne can automatically detect resource and id parameters from the current route.

components/products/show.tsx
import { useOne } from "@refinedev/core";

const { data: productResponse } = useOne({ resource: "products", id: "1" });

console.log(productResponse.data); // { id: "1", title: "Product 1", ... }

const { data: productResponse } = useOne();

console.log(productResponse.data); // { id: "1", title: "Product 1", ... }

useShow​

useShow can automatically detect resource and id parameters from the current route.

components/products/show.tsx
import { useShow } from "@refinedev/core";

const { queryResult: showResponse } = useShow({
  resource: "products",
  id: "1",
});

console.log(showResponse.data.data); // { id: "1", title: "Product 1", ... }

const { queryResult: showResponse } = useShow();

console.log(showResponse.data.data); // { id: "1", title: "Product 1", ... }

useList​

useList can automatically detect resource parameter from the current route.

components/products/list.tsx
import { useList } from "@refinedev/core";

const { data: listResponse } = useList({ resource: "products" });

console.log(listResponse.data); // [{ id: "1", title: "Product 1", ... }, { id: "2", title: "Product 2", ... }]
console.log(listResponse.total); // 32 - total number of unpaginated records

const { data: listResponse } = useList();

console.log(listResponse.data); // [{ id: "1", title: "Product 1", ... }, { id: "2", title: "Product 2", ... }]
console.log(listResponse.total); // 32 - total number of unpaginated records
CAUTION

config.pagination, config.filters, config.sorters will not be automatically detected from the current route.

The routerProvider Interface​

A router integration of Refine consists of a set of basic implementations for:

  • Ability to navigate between pages/routes
  • An interface to interact with the parameters and query strings of the current route
  • An utility to navigate back in the history
  • A simple component to use for anchor tags

These implementations will be provided via routerProvider which expects an object with the following methods:

  • go: A function that accepts an object and returns a function that handles the navigation.
  • back: A function that returns a function that handles the navigation back in the history.
  • parse: A function that returns a function that parses the current route and returns an object.
  • Link: A React component that accepts a to prop and renders a component that handles the navigation to the given to prop.

While all these methods are optional, if you're working on creating a custom router integration, you'll be able to incrementally add more features and adopt more of Refine's features by implementing more of these methods.

To learn more about the routerProvider interface, check out the Router Provider section of the Core API Reference.

Previous
Tables
Next
Authentication