Notification Provider
refine let's you set a notification API by providing the notificationProvider property to the <Refine> component.
notificationProvider is an object with close and open methods. refine uses these methods to show and hide notifications. These methods can be called from anywhere in the application with useNotification hook.
An notificationProvider must include following methods:
const notificationProvider = {
show: () => {},
close: () => {},
};
And these methods types like this:
interface NotificationProvider {
open: (params: OpenNotificationParams) => void;
close: (key: string) => void;
}
interface OpenNotificationParams {
key?: string;
message: string;
type: "success" | "error" | "progress";
description?: string;
cancelMutation?: () => void;
undoableTimeout?: number;
}
Usage​
To use notificationProvider in refine, we have to pass the notificationProvider to the <Refine> component.
import { Refine, NotificationProvider } from "@refinedev/core";
const notificationProvider: NotificationProvider = {
open: () => {},
close: () => {},
};
const App = () => {
return (
<Refine
notificationProvider={notificationProvider}
/* ... */
>
{/* ... */}
</Refine>
);
};
By default, refine doesn't require notificationProvider configuration.
If an notificationProvider property is not provided, refine will use the default notificationProvider, which lets the app work without an notification.
If your app doesn't require notification, no further setup is necessary for the app to work.
Built-in Notification Providers​
If you're looking for a complete notification infrastructure, refine has out-of-the-box support for the libraries below:
- Ant Design
- Material UI
- Mantine
- Chakra UI
import { notificationProvider } from "@refinedev/antd";
return (
<Refine
//...
notificationProvider={notificationProvider}
/>
);
import { notificationProvider, RefineSnackbarProvider } from "@refinedev/mui";
return (
<RefineSnackbarProvider>
<Refine
//...
notificationProvider={notificationProvider}
/>
</RefineSnackbarProvider>
);
import { notificationProvider } from "@refinedev/mantine";
import { NotificationsProvider } from "@mantine/notifications";
return (
<NotificationsProvider position="top-right">
<Refine
//...
notificationProvider={notificationProvider}
/>
</NotificationsProvider>
);
import { notificationProvider } from "@refinedev/chakra";
return (
<Refine
//...
notificationProvider={notificationProvider()}
/>
);
Creating a notificationProvider from scratch​
We will now build a simple notificationProvider from scratch to show the logic of how notificationProvider methods interact with the app. For this, we will use the react-toastify package, which is very popular in the React Ecosystem. If you want to use another notification library, you can use the same approach.
Before we start, we need set up the react-toastify requirements.
import { Refine } from "@refinedev/core";
import { ToastContainer } from "react-toastify";
import "react-toastify/dist/ReactToastify.css";
const App: React.FC = () => {
return (
<Refine
/* ...*/
>
{/* ... */}
<ToastContainer />
</Refine>
);
};
export default App;
open​
refine calls this method when it wants to open a notification. It also helps you to get the right notification by sending some parameters to the refine open method. For example, message, description, etc.
Here we open a notification with react-toastify:
import { toast } from "react-toastify";
const notificationProvider: NotificationProvider = {
open: ({ message, key, type }) => {
toast(message, {
toastId: key,
type,
});
},
};
Let's make it so that the previous notification is updated when the notification is called again with the same key instead of creating a new one each time. We can use toast.isActive(key) for this since it returns true if the notification is still active.
import { toast } from "react-toastify";
const notificationProvider: NotificationProvider = {
open: ({ message, key, type }) => {
if (toast.isActive(key)) {
toast.update(key, {
render: message,
type,
});
} else {
toast(message, {
toastId: key,
type,
});
}
},
};
Now, let's create a custom notification when the mutation mode is undoable. In this case, refine sends the notification's type as progress as well as cancelMutation and undoableTimeout.
undoableTimeout decreases by 1 every second until it reaches 0, at which point the notification is closed. The open method is called again with the samekey each countdown. So, the notification should be updated with the newundoableTimeout value.
import { toast } from "react-toastify";
const notificationProvider: NotificationProvider = {
open: ({ message, key, type }) => {
if (type === "progress") {
if (toast.isActive(key)) {
toast.update(key, {
progress: undoableTimeout && (undoableTimeout / 10) * 2,
render: (
<UndoableNotification
message={message}
cancelMutation={cancelMutation}
/>
),
type: "default",
});
} else {
toast(
<UndoableNotification
message={message}
cancelMutation={cancelMutation}
/>,
{
toastId: key,
updateId: key,
closeOnClick: false,
closeButton: false,
autoClose: false,
progress: undoableTimeout && (undoableTimeout / 10) * 2,
},
);
}
} else {
if (toast.isActive(key)) {
toast.update(key, {
render: message,
closeButton: true,
autoClose: 5000,
type,
});
} else {
toast(message, {
toastId: key,
type,
});
}
}
},
};
See UndoableNotification Component
type UndoableNotification = {
message: string;
cancelMutation?: () => void;
closeToast?: () => void;
};
export const UndoableNotification: React.FC<UndoableNotification> = ({
closeToast,
cancelMutation,
message,
}) => {
return (
<div>
<p>{message}</p>
<button
onClick={() => {
cancelMutation?.();
closeToast?.();
}}
>
Undo
</button>
</div>
);
};
We add closeButton and autoClose for progress notifications, which are not closable by default to allow users to close them when the progress is done.
The open method will be accessible via useNotification hook.
import { useNotification } from "@refinedev/core";
const { open } = useNotification();
open?.({
type: "success",
message: "Hey",
description: "I <3 Refine",
key: "unique-id",
});
close​
refine calls this method when it wants to close a notification. refine pass the key of the notification to the close method. So, we can handle the notification close logic with this key.
import { toast } from "react-toastify";
const notificationProvider: NotificationProvider = {
//...
close: (key) => toast.dismiss(key),
};
close method will be accessible via useNotification hook.
import { useNotification } from "@refinedev/core";
const { close } = useNotification();
close?.("displayed-notification-key");
Example​
npm create refine-app@latest -- --example with-react-toastify