useCustomMutation
useCustomMutation
is used when sending custom mutation requests using the TanStack Query advantages. It is an extended version of TanStack Query's useMutation
and not only supports all features of the mutation but also adds some extra features.
It uses the custom
method as the mutation function from the dataProvider
which is passed to <Refine>
.
Use Cases
useCustomMutation
should not be used when creating, updating, or deleting a resource. Following hooks should be used for these instead: useCreate, useUpdate or useDelete.
This is because useCustomMutation
, unlike other data hooks, does not invalidate queries and therefore will not update the application state either.
If you need to custom query request, use the useCustom hook.
Basic Usageโ
The useCustomMutation
hook returns many useful properties and methods. One of them is the mutate
method which expects values
, method
, and url
as parameters. These parameters will be passed to the custom
method from the dataProvider
as parameters. Additionally, the mutation
object contains all the TanStack Query's useMutation
return values.
import { useCustomMutation, useApiUrl } from "@refinedev/core";
interface ICategory {
id: number;
title: string;
}
const apiUrl = useApiUrl();
const { mutate, mutation } = useCustomMutation<ICategory>();
mutate({
url: `${API_URL}/categories`,
method: "post",
values: {
title: "New Category",
},
});
// You can access mutation state through the mutation object:
console.log(mutation.isLoading); // mutation loading state
console.log(mutation.data); // mutation response data
console.log(mutation.error); // mutation error
Propertiesโ
mutationOptionsโ
mutationOptions
is used to pass options to the useMutation
hook. It is useful when you want to pass additional options to the useMutation
hook.
For more information, refer to the
useMutation
documentation โ
useCustomMutation({
mutationOptions: {
retry: 3,
},
});
mutationOptions
does not support onSuccess
and onError
props because they override the default onSuccess
and onError
functions. If you want to use these props, you can pass them to mutate functions like this:
const { mutate, mutation } = useCustomMutation();
mutate(
{
url: `${API_URL}/categories`,
method: "post",
values: {
title: "New Category",
},
},
{
onError: (error, variables, context) => {
// An error occurred!
},
onSuccess: (data, variables, context) => {
// Let's celebrate!
},
},
);
Mutation Parametersโ
url requiredโ
It will be passed to the custom
method from the dataProvider
as a parameter. It is usually used to specify the endpoint of the request.
const { mutate, mutation } = useCustomMutation();
mutate({
url: "www.example.com/api/update-products",
});
method requiredโ
It will be passed to the custom
method from the dataProvider
as a parameter. It is usually used to specify the HTTP method of the request.
const { mutate, mutation } = useCustomMutation();
mutate({
method: "post",
});
values requiredโ
It will be passed to the custom
method from the dataProvider
as a parameter. The parameter is usually used as the data to be sent with the request.
const { mutate, mutation } = useCustomMutation();
mutate({
values: {
name: "New Category",
description: "New Category Description",
},
});
config.headersโ
It will be passed to the custom
method from the dataProvider
as a parameter. It can be used to specify the headers of the request.
const { mutate, mutation } = useCustomMutation();
mutate({
config: {
headers: {
"x-custom-header": "foo-bar",
},
},
});
successNotificationโ
NotificationProvider
is required for this prop to work.
This prop allows you to customize the success notification that shows up when the data is fetched successfully and useCustomMutation
calls the open
function from NotificationProvider
:
const { mutate, mutation } = useCustomMutation();
mutate({
successNotification: (data, values) => {
return {
message: `${data.title} Successfully fetched.`,
description: "Success with no errors",
type: "success",
};
},
});
errorNotificationโ
NotificationProvider
is required for this prop to work.
After data fetching is failed, useCustomMutation
will call open
function from NotificationProvider
to show an error notification. With this prop, you can customize the error notification.
const { mutate, mutation } = useCustomMutation();
mutate({
errorNotification: (data, values) => {
return {
message: `Something went wrong when getting ${data.id}`,
description: "Error",
type: "error",
};
},
});
metaโ
meta
is a special property that can be used to pass additional information to data provider methods for the following purposes:
- Customizing the data provider methods for specific use cases.
- Generating GraphQL queries using plain JavaScript Objects (JSON).
In the following example, meta
is passed to the custom
method from the dataProvider
as a parameter.
const { mutate, mutation } = useCustomMutation();
mutate({
meta: {
foo: "bar",
},
});
const myDataProvider = {
//...
custom: async ({
url,
method,
sort,
filters,
payload,
query,
headers,
meta,
}) => {
const foo = meta?.foo;
console.log(foo); // "bar"
//...
},
//...
};
For more information, refer to the
meta
section of the General Concepts documentationโ
dataProviderNameโ
If there is more than one dataProvider
, you can specify which one to use by passing the dataProviderName
prop. It is useful when you have a different data provider for different resources.
const { mutate, mutation } = useCustomMutation();
mutate({
dataProviderName: "second-data-provider",
});
overtimeOptionsโ
If you want loading overtime for the request, you can pass the overtimeOptions
prop to the this hook. It is useful when you want to show a loading indicator when the request takes too long.
interval
is the time interval in milliseconds. onInterval
is the function that will be called on each interval.
Return overtime
object from this hook. elapsedTime
is the elapsed time in milliseconds. It becomes undefined
when the request is completed.
const { overtime } = useCustomMutation({
//...
overtimeOptions: {
interval: 1000,
onInterval(elapsedInterval) {
console.log(elapsedInterval);
},
},
});
console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
// You can use it like this:
{
elapsedTime >= 4000 && <div>this takes a bit longer than expected</div>;
}
Return Valuesโ
Returns an object with TanStack Query's useMutation
return values.
Refer to the useMutation
documentation for more information โ
Additional Valuesโ
overtimeโ
overtime
object is returned from this hook. elapsedTime
is the elapsed time in milliseconds. It becomes undefined
when the request is completed.
const { overtime } = useCustomMutation();
console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
API Referenceโ
Mutation Parametersโ
Property | Description | Type |
---|---|---|
url ๏นก | URL | string |
method ๏นก | Method | post , put , patch , delete |
values ๏นก | Values for mutation function | TVariables |
config | The config of your request. You can send headers using this field. | { headers?: {}; } |
successNotification | Successful mutation notification | SuccessErrorNotification |
errorNotification | Unsuccessful mutation notification | SuccessErrorNotification |
meta | Meta data query for dataProvider | MetaDataQuery |
dataProviderName | If there is more than one dataProvider , you should use the dataProviderName that you will use. | string |
Type Parametersโ
Property | Description | Type | Default |
---|---|---|---|
TData | Result data of the query. Extends BaseRecord | BaseRecord | BaseRecord |
TError | Custom error object that extends HttpError | HttpError | HttpError |
TQuery | Values for query params. | TQuery | unknown |
TPayload | Values for params. | TPayload | unknown |
Return valueโ
Property | Description | Type |
---|---|---|
mutation | Result of the TanStack Query's useMutation | UseMutationResult<{ data: TData }, TError, { resource: string; values: TVariables; }, unknown> |
mutate | Mutation function | (params?: { url?: string, method?: string, values?: TVariables, ... }) => void |
mutateAsync | Async mutation function | (params?: { url?: string, method?: string, values?: TVariables, ... }) => Promise<{ data: TData }> |
overtime | Overtime loading information | { elapsedTime?: number } |