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