Frequently Asked Questions

You may need to modify the form data before it is sent to the API for various reasons. For example, you may want to add a field to the form data or change the value of a field before submitting it to the API. This can be achieved easily by Refine's useForm implementations.

Check out the Modifying Data Before Submission section in Forms guide to learn how to achieve this.

Refine automatically invalidates the affected resources after mutations. However, in some cases you may want to refetch manually.

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

// All "data" related hooks provided by Refine can use queryResult' refetch function
const { tableQueryResult: { refetch } } = useTable();
const { queryResult: { refetch } } = useForm();
...
...
const { queryResult: { refetch } } = useShow();
...
...

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

const invalidate = useInvalidate();

// To invalidate the list and many states of the Posts resource
invalidate({
  resource: "posts",
  invalidates: ["list", "many"],
});

// To invalidate the state of a Posts with an id of 1
invalidate({
  resource: "posts",
  invalidates: ["detail"],
  id: 1,
});

// To invalidate the list and many states of the Posts resource of the dataProvider named "second-data-provider"
invalidate({
  resource: "posts",
  dataProviderName: "second-data-provider",
  invalidates: ["list"],
});

// To invalidate all states of dataprovider named "second-data-provider"
invalidate({
  dataProviderName: "second-data-provider",
  invalidates: ["all"],
});

Refine's way of doing this is with the resource property on all data hooks. You can think of the resource property as the URL.

For example, If you want to make a request of the URL /user/1/posts.

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

useTable({
  resource: "/users/1/posts",
});

Note that data related hooks (useMany, useOne, etc.) can also accept all useQuery options, which allows you to implement dependent queries whereby a query is only run after a certain data is available. This is particularly useful if you want useMany to only run after a certain data is available and not on load.

Refer to react-query docs on dependent queries for more information →

• Suppose you want this query to run after categoryIds is fetched by a preceding query, you can set enabled to categoryIds.length > 0. This will ensure that useMany is only run after categoryIds is fetched.

useMany({
  resource: "categories",
  ids: categoryIds,
  queryOptions: { enabled: categoryIds.length > 0 },
});

Although Refine is written in TypeScript and it is recommended to use TypeScript, you can also work with Javascript without any problems. Check out the Refine with Javascript example →

In some cases, you may need to override functions of Refine data providers. The simplest way to do this is to use the Spread syntax

Below code sample, overrides the update function of the @refinedev/simple-rest. You can apply custom logic to the data provider methods or handle a custom meta property for your needs.

import dataProvider from "@refinedev/simple-rest";

const simpleRestProvider = dataProvider("API_URL");
const myDataProvider = {
  ...simpleRestProvider,
  update: async ({ resource, id, variables, meta }) => {
    console.log("Overriding the update function");

    // You can either send a request from scratch or use the original function
    return await simpleRestProvider.update({ resource, id, variables, meta });
  },
};

<Refine dataProvider={myDataProvider} />;

This is the expected behavior if you use [<React.StrictMode>][https://react.dev/reference/react/StrictMode]. In this mode, React will render the components twice in development mode to identify unsafe life cycles, unexpected side effects, and legacy or deprecated APIs. It's used for highlighting possible problems. You can also check out the related issue on the TanStack Query repository.

<Sider /> components use the resources property of the <Refine> component to render the navigation links. If a resource has a list property, it will be rendered as a navigation link in the sider. To add a custom item to the sider, you can use three different approaches:

The first and simplest way is to use the resources property on the <Refine> component. The <Sider> component shows the resources whose list property is set. So, you can have an extra navigation link by adding a resource with the list attribute.

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

<Refine
    ...
    resources={[
        {
            name: "dashboard",
            list: "/",
            meta: {
                label: "Dashboard",
                icon: "🏠",
            },
        },
    ]}
/>;

The second way is to use the render property of the <Sider> component. The render property is a function that receives an object with the items and logout properties. The items property is the list of navigation items and the logout property is the logout button.

import { Layout, Sider } from "@refinedev/antd";

const CustomSider = () => {
  return (
    <Sider
      render={({ items, logout }) => {
        return (
          <>
            <a href="https://refine.dev/">👋 Navigation Link</a>
            {items}
            {logout}
          </>
        );
      }}
    />
  );
};

const CustomLayout = () => {
  return <Layout Sider={CustomSider}>...</Layout>;
};

import { Layout, Sider } from "@refinedev/mui";

const CustomSider = () => {
  return (
    <Sider
      render={({ items, logout }) => {
        return (
          <>
            <a href="https://refine.dev/">👋 Navigation Link</a>
            {items}
            {logout}
          </>
        );
      }}
    />
  );
};

const CustomLayout = () => {
  return <Layout Sider={CustomSider}>...</Layout>;
};

import { Layout, Sider } from "@refinedev/mantine";

const CustomSider = () => {
  return (
    <Sider
      render={({ items, logout }) => {
        return (
          <>
            <a href="https://refine.dev/">👋 Navigation Link</a>
            {items}
            {logout}
          </>
        );
      }}
    />
  );
};

const CustomLayout = () => {
  return <Layout Sider={CustomSider}>...</Layout>;
};

import { Layout, Sider } from "@refinedev/chakra-ui";

const CustomSider = () => {
  return (
    <Sider
      render={({ items, logout }) => {
        return (
          <>
            <a href="https://refine.dev/">👋 Navigation Link</a>
            {items}
            {logout}
          </>
        );
      }}
    />
  );
};

const CustomLayout = () => {
  return <Layout Sider={CustomSider}>...</Layout>;
};

The third way is to use the swizzle command.

You can use the command to copy the default Sider component to your project. This will allow you to customize the sider as you want.

Refer to the swizzle section of Development guide. →

Refine's useMenu hook and <Sider /> components use the resources property of the <Refine> component to render the navigation links. If a resource has a list property, it will be rendered as a navigation link in the sider. To hide a resource from the menu, you can use the meta.hide property of the resource.

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

const App = () => (
  <Refine
    ...
    resources={[
      {
        name: "posts",
        list: "/posts",
        meta: {
          label: "Posts",
          icon: "📝",
        },
      },
      {
        name: "users",
        list: "/users",
        meta: {
          // Users resource will be hidden from the menu but will be accessible via the URL
          hide: true,
        },
      },
    ]}
  />
);

To remove the GitHub Banner, you need to find and remove the <GitHubBanner /> component from your React application. The specific location of this component may vary depending on the React platform you are using.

Here are the locations where you can find and remove the <GitHubBanner /> component based on different React platforms:

• Vite: src/App.tsx - See an example
• Next.js: src/app/layout.tsx - See an example
• Remix: app/root.tsx - See an example

The error message "Module 'X' has no exported member 'Y'" typically occurs when using pnpm due to its cache system. We are aware of this issue and are actively working on resolving it by updating our peer dependencies with each version release. However, this is still a work in progress. In the meantime, you can resolve this error by using the npm i <module-name>@latest command.

Here are a couple of examples of reported errors and their corresponding fix:

1. Error: "Module '@refinedev/mantine' has no exported member 'HamburgerMenu'"

   • Solution: Run npm i @refinedev/mantine@latest to install the latest version of the @refinedev/mantine module.

2. Error: "Module '@refinedev/antd' has no exported member 'ThemedLayoutV2'"

   • Solution: Execute npm i @refinedev/antd@latest to install the latest version of the @refinedev/antd module.

By following these steps and updating to the latest module versions, you should be able to resolve the "not exported" error.

Until @refinedev/core's version 4.28.2, Refine had the @tanstack/react-query-devtools package available by default. However, this package has been removed from the core package and is no longer available by default.

We're recommending @refinedev/devtools as an alternative to @tanstack/react-query-devtools. @refinedev/devtools is tailored for Refine and provides more detailed information about the queries and mutations with its monitoring panel and much more.

Refine invalidates and refetches the related queries after a successful mutation. To have a better understanding of how invalidation works in Refine, check out the State Management section of General Concepts guide.

When you're implementing client side pagination with the pagination.mode set to "client," you might run into issues when applying client side filtering and sorting. This is due to the fact that client side filtering and sorting are applied to the sliced data, not the whole data. To ensure that the client side filtering and sorting are applied to the whole data, you need to use the pagination.mode: "off" prop.

When working with forms and mutations, using only client side validation might not be enough. You may also need to validate the data on the server side. Refine provides an interface HttpError to propagate the server side validation errors to the form values. You can use this interface to handle server side validation errors.

To learn more about server side validation and see an example, check out the Server Side Validation section of the Forms guide.

When working without a network connection, @tanstack/query prevents requests from being made until a successful connection is established. You might feel frustrated and wonder,

Why can't I work with my own data? Must I use an internet connection to run this library?

Don't worry; according to the @tanstack/query documentation, you can simply add the networkMode: "always" option to the reactQuery props on the <Refine/> component.

<Refine
  // ...
  options: {
    // ...
    reactQuery: {
      clientConfig: {
        defaultOptions: {
          queries: { // For fetching data
            networkMode: "always", // Apply this to mutations as well, as shown below
          },
          mutations: { // For posting data
            networkMode: "always" // It defaults to "online," preventing requests when there is no connection
          },
        },
      },
    },
  }
/>

When working with Refine in development environment you may receive network errors in the console. Browsers will log network errors regardless of the status of the Promise. This is a common behavior in development environments and does not affect the functionality of the application.

Still, there two common errors that you may encounter when working with Refine in development environment but you can safely ignore them:

• 401 (Unauthorized) from :5001/api/.auth/sessions/whoami - This error is related with the Refine's Devtools and logged if there are no active authentication sessions in Devtools. You can get rid of this error by logging in to the Devtools.

• Numerous 404 (Not Found) errors when using Refine's Inferencer - These errors are related with the Inferencer component since the main logic behing Inferencer components are to infer the data structure from the API. When trying to infer the data structure, Inferencer may send requests to the API to determine relationships between resources. You can safely ignore these errors as they are not affecting the functionality of the application. To learn more about the functionality of Inferencer, check out the How the fields are inferred? section in Inferencer docs.

If you have any other network errors thrown by Refine and have no relation with the above mentioned errors or not caused by your project's logic, please reach out to us via GitHub Issues or our Discord Community.