useUpdateMany

useUpdateMany is a modified version of react-query's useMutation for multiple update mutations. It uses updateMany method as mutation function from the dataProvider which is passed to <Refine>.

tip

If your data provider didn't implement updateMany method, useUpdateMany will use update method multiple times instead.

Features

• Shows notifications after the mutation succeeds, fails, or gets canceled.

• Automatically invalidates list and getOne queries after the mutation is succesfully run. Refer to React Query docs for detailed information →

• Supports mutation mode.

Usage

Let's say that we have a resource named posts.

https://api.fake-rest.refine.dev/posts

{
    [
        {
            id: 1,
            status: "published",
        },
        {
            id: 2,
            status: "rejected",
        },
    ];
}

type PostMutationResult = {
    id: number;
    status: "published" | "draft" | "rejected";
};

import { useUpdateMany } from "@pankod/refine-core";

const { mutate } = useUpdateMany<PostMutationResult>();

mutate({
    resource: "posts",
    ids: [1, 2],
    values: { status: "draft" },
});

tip

mutate can also accept lifecycle methods like onSuccess and onError.

mutate(
    {
        resource: "categories",
        ids: [1, 2],
        values: { status: "draft" },
    },
    {
        onError: (error, variables, context) => {
            // An error happened!
        },
        onSuccess: (data, variables, context) => {
            // Let's celebrate!
        },
    },
);

Refer to react-query docs for further information. →

After mutation runs posts will be updated as below:

https://api.fake-rest.refine.dev/posts

{
    [
        {
            id: 1,
            status: "draft",
        },
        {
            id: 2,
            status: "draft",
        },
    ];
}

note

Queries that use /posts endpoint will be automatically invalidated to show the updated data. For example, data returned from useList and useOne will be automatically updated.

tip

useUpdateMany returns react-query's useMutation result which includes a lot properties, one of which being mutate.

info

Values passed to mutate must have these types:

{
    resource: string;
    ids: BaseKey[];
    values: TVariables = {};
    mutationMode?: MutationMode;
    undoableTimeout?: number;
    onCancel?: (cancelMutation: () => void) => void;
}

Mutation mode

Mutation mode determines the mode which mutation runs with.

import { useUpdateMany } from "@pankod/refine-core";

const { mutate } = useUpdateMany();

mutate({
    resource: "posts",
    ids: [1, 2],
    values: { status: "draft" },
    mutationMode: "optimistic",
});

Refer to mutation mode docs for further information. →

Creating a custom method for cancelling mutations

You can pass a custom cancel callback to useUpdateMany. This callback is triggered instead of the default one when undo button is clicked when mutationMode = "undoable".

caution

Default behaviour on undo action includes notifications. If a custom callback is passed this notification will not appear.

danger

Passed callback will receive a function that actually cancels the mutation. Don't forget to run this function to cancel the mutation on undoable mode.

import { useUpdateMany } from "@pankod/refine-core";

const customOnCancel = (cancelMutation: () => void) => {
    cancelMutation();
    // rest of custom cancel logic...
};

const { mutate } = useUpdateMany();

mutate({
    resource: "posts",
    ids: [1, 2],
    values: { status: "draft" },
    mutationMode: "undoable",
    undoableTimeout: 7500,
    onCancel: customOnCancel,
});

After 7.5 seconds the mutation will be executed. The mutation can be cancelled within that 7.5 seconds. If cancelled customOnCancel will be executed and the request will not be sent.

API

Properties

Property	Description	Type	Default
resource Required	Resource name for API data interactions	string
id Required	id for mutation function	BaseKey[]
values Required	Values for mutation function	TVariables[]	[{}]
mutationMode	Determines when mutations are executed	"pessimistic | "optimistic | "undoable"	"pessimistic"*
undoableTimeout	Duration to wait before executing the mutation when mutationMode = "undoable"	number	5000ms*
onCancel	Callback that runs when undo button is clicked on mutationMode = "undoable"	(cancelMutation: () => void) => void
successNotification	Successful Mutation notification	SuccessErrorNotification	"Successfully updated resource"
errorNotification	Unsuccessful Mutation notification	SuccessErrorNotification	"Error when updating resource (status code: statusCode)"
metaData	Metadata query for dataProvider	MetaDataQuery	{}
dataProviderName	If there is more than one dataProvider, you should use the dataProviderName that you will use.	string	default
invalidates	You can use it to manage the invalidations that will occur at the end of the mutation.	all, resourceAll, list, many, detail, false	["list", "many", "detail"]

*: These props have default values in RefineContext and can also be set on <Refine)> component. useUpdateMany will use what is passed to <Refine> as default but a local value will override it.

Type Parameters

Property	Desription	Type	Default
TData	Result data of the mutation. Extends BaseRecord	BaseRecord	BaseRecord
TError	Custom error object that extends HttpError	HttpError	HttpError
TVariables	Values for mutation function	{}	{}

Return value

Description	Type
Result of the react-query's useMutation	UseMutationResult< { data: TData }, TError, { resource:string; ids: BaseKey[]; values: TVariables; }, UpdateContext>*

* UpdateContext is an internal type.