Mutation Mode
Overview
Mutation mode determines which mode the mutation runs with. Mutations can run under three different modes: pessimistic
, optimistic
and undoable
.
Each mode corresponds to a different type of user experience.
Modes
We'll show usages of modes with editing a record examples.
pessimistic
The mutation runs immediately. Redirection and UI updates are executed after the mutation returns successfuly.
You can experience an example of this below using the edit page.
When the user clicks on save button, request to the API happens directly and after successful response, list page updates with newly edited record.
optimistic
The mutation is applied locally, redirection and UI updates are executed immediately as if the mutation is succesful. If mutation returns with error, UI updates to show data prior to the mutation.
When the user clicks on save button, request to the API happens directly and list page updates with edited data immediately without waiting API response.
undoable
The mutation is applied locally, redirection and UI updates are executed immediately as if the mutation is succesful. Waits for a customizable amount of timeout period before mutation is applied. During the timeout, mutation can be cancelled from the notification with an undo button and UI will revert back accordingly.
When the user clicks on save button, request isn't sent to API immediately however list page updates with edited data. It waits for a period of time while the user can cancel the mutation. If the mutation is cancelled, locally applied edit is undone.
Usage
Mutation mode can be set application-wide in <Refine>
component.
<Refine
...
options={{ mutationMode: "optimistic" }}
/>
Its default value is
pessimistic
.
It can also be set in supported data hooks and form hooks for fine-grained configuration.
import { useUpdate } from "@refinedev/core";
const { mutate } = useUpdate();
mutate({
resource: "categories",
id: "2",
values: { title: "New Category Title" },
mutationMode: "optimistic",
});
Mutation mode passed to
<Refine>
will be overriden by the mutation mode passed to data or form hooks and components.
Supported data hooks
Example
- Antd Design
- Chakra UI
- Mantine
- Material UI
npm create refine-app@latest -- --example form-antd-mutation-mode
npm create refine-app@latest -- --example form-chakra-ui-mutation-mode
npm create refine-app@latest -- --example form-mantine-mutation-mode
npm create refine-app@latest -- --example form-material-ui-mutation-mode