useForm

Basic usage of the useForm hook demonstrates how to use the hook in all three modes, create, edit, and clone.

create.tsxedit.tsxclone.tsx

import React from "react";
import { useForm, HttpError, BaseKey } from "@refinedev/core";

export const Create: React.FC = () => {
    const { onFinish } = useForm<IProduct, HttpError, FormValues>({
        resource: "products",
        action: "create",
        redirect: "show", // redirect to show page after form submission, defaults to "list"
    });

    const [values, setValues] = React.useState<FormValues>({ name: "", material: "" });

    const onSubmit = (e) => {
        e.preventDefault();
        onFinish(values);
    };

    return (
        <form onSubmit={onSubmit}>
            <label htmlFor="name">Name</label>
            <input
                name="name"
                placeholder="Name"
                value={values.name}
                onChange={(e) => setValues({ ...values, name: e.target.value })}
            />
            <label htmlFor="material">Material</label>
            <input
                name="material"
                placeholder="Material"
                value={values.material}
                onChange={(e) => setValues({ ...values, material: e.target.value })}
            />
            <button type="submit">Submit</button>
        </form>
    );
};

interface IProduct {
    id: BaseKey;
    name: string;
    material: string;
}

interface FormValues {
    name?: string;
    material?: string;
}

Open Sandbox

The action that will be performed with the submission of the form. Can be create, edit, or clone. If not specified, it will be determined by the current route or fallback to create.

useForm({ action: "create" });

In create action, useForm will follow the flow below:

After form is submitted:

1. useForm calls onFinish function with the form values.
2. onFinish function calls useCreate with the form values.
3. useCreate calls dataProvider's create function and returns the response.
4. useForm calls onSuccess or onError function with the response, depending on the response status.
5. After a successful mutation, useForm will invalidate the queries specified in invalidates prop.
6. onSuccess or onError function then calls the open function of the notificationProvider to inform the user.
7. useForm redirects to the list page.

In edit action, useForm will follow the flow below:

When useForm is mounted, it calls useOne hook to retrieve the record to be edited. The id for the record is obtained from the props or the current route.

After form is submitted:

1. useForm calls onFinish function with the form values.
2. onFinish function calls useUpdate with the form values.
3. If the mutation mode is optimistic or undoable, useForm will update the query cache with the form values immediately after the mutation is triggered.
4. If the mutation mode is undoable, useForm will display a notification with a countdown to undo the mutation.
5. useUpdate calls dataProvider's update function and returns the response.
6. useForm calls onSuccess or onError function with the response, depending on the response status.
7. If the mutation fails, useForm will revert the query cache to the previous values made in step 3.
8. After a successful mutation, useForm will invalidate the queries specified in invalidates prop.
9. onSuccess or onError function then calls the open function of the notificationProvider to inform the user.
10. useForm redirects to the list page.

When useForm is mounted, it calls useOne hook to retrieve the record to be cloned. The id for the record is obtained from the props or the current route.

After form is submitted:

1. useForm calls onFinish function with the form values.
2. onFinish function calls useCreate with the form values.
3. useUpdate calls dataProvider's update function and returns the response.
4. useForm calls onSuccess or onError function with the response, depending on the response status.
5. After a successful mutation, useForm will invalidate the queries specified in invalidates prop.
6. onSuccess or onError function then calls the open function of the notificationProvider to inform the user.
7. useForm redirects to the list page.

The resource name or identifier that will be used for the form. If not specified, it will be determined by the current route.

useForm({ resource: "products" });

The ID of the record that will be used for the action. If not specified, it will be determined by the current route. Required for edit and clone actions.

useForm({
  id: 123,
});

The redirection behavior after the form submission. It can be list, edit, show, create, or false. By default it will be list or whatever is defined in the Refine's global options.

useForm({ redirect: "show" });

Callback function to be called after a successful mutation. It will be called with the mutation result and variables.

useForm({
    onMutationSuccess: (
        data, // Mutation result, depending on the action its the response of `useCreate` or `useUpdate`
        variables, // Variables/form values that were used for the mutation
        context, // React Query's context for the mutation
        isAutoSave, // Boolean value indicating if the mutation was triggered by auto-save or not
    ) => { ... }
});

Callback function to be called after a failed mutation. It will be called with the mutation error and variables.

useForm({
    onMutationError: (
        error, // Mutation error, depending on the action its the error response of `useCreate` or `useUpdate`
        variables, // Variables/form values that were used for the mutation
        context, // React Query's context for the mutation
        isAutoSave, // Boolean value indicating if the mutation was triggered by auto-save or not
    ) => { ... }
});

Determines the scope of the invalidation after a successful mutation. Can be array of list, many, detail, resourceAll, all or false. By default, create and clone actions will invalidate list and many. edit action will invalidate list, many and detail queries.

useForm({ invalidates: ["list", "many"] });

Name of the data provider to be used in API interactions. Useful when there are more than one data providers defined.

useForm({ dataProviderName: "store" });

Behavior of the mutation, can either be pessimistic, optimistic or undoable. By default, pessimistic or whatever is defined in the Refine's global options.

useForm({ mutationMode: "optimistic" });

NotificationProvider is required for this prop to work.

Customization options for the notification that will be shown after a successful mutation.

useForm({
  // Can also be a static object if you don't need to access the data, values or resource.
  // By setting it to `false`, you can disable the notification.
  successNotification: (data, values, resource) => {
    return {
      message: `Successfully created ${data.title}`,
      description: "good job!",
      type: "success",
    };
  },
});

NotificationProvider is required for this prop to work.

Customization options for the notification that will be shown after a failed mutation.

useForm({
  // Can also be a static object if you don't need to access the data, values or resource.
  // By setting it to `false`, you can disable the notification.
  errorNotification: (error, values, resource) => {
    return {
      message: `Failed to create ${values.title}`,
      description: error.message,
      type: "error",
    };
  },
});

Additional information that will be passed to the data provider. Can be used to handle special cases in the data provider, generating GraphQL queries or handling additional parameters in the redirection routes.

useForm({ meta: { headers: { "x-greetings": "hello world" } } });

Meta data values to be used in the internal useOne call for the edit and clone actions. These values will take precedence over the meta values.

useForm({ meta: { headers: { "x-greetings": "hello mars" } } });

Meta data values to be used in the internal useCreate and useUpdate calls for form submissions. These values will take precedence over the meta values.

useForm({ meta: { headers: { "x-greetings": "hello pluto" } } });

Options to be used in the internal useOne call for the edit and clone actions.

useForm({
  queryOptions: { retry: 3 },
});

Options to be used in the internal useCreate call for the create and clone actions.

useForm({
  createMutationOptions: { retry: 3 },
});

Options to be used in the internal useUpdate call for the edit action.

useForm({
  updateMutationOptions: { retry: 3 },
});

LiveProvider is required for this prop to work.

Behavior of how to handle received real-time updates, can be auto, manual or off. By default, auto or whatever is defined in the Refine's global options.

useForm({ liveMode: "auto" });

A callback function that will be called when a related real-time event is received.

useForm({
  onLiveEvent: (event) => {
    console.log(event);
  },
});

Additional parameters to be used in the liveProvider's subscribe method.

useForm({
  liveParams: {
    foo: "bar",
  },
});

A set of options to be used for the overtime loading state. Useful when the API is slow to respond and a visual feedback is needed to indicate that the request is still in progress. overtimeOptions accept interval as number to determine the ticking intervals and onInterval to be called on each tick. useForm also returns overtime object with elapsedTime value that can be used for the feedback.

const { overtime } = useForm({
  interval: 1000,
  onInterval(elapsedTime) {
    console.log(elapsedTime);
  },
});

Auto-save behavior of the form. Can have enabled to toggle auto-save, debounce to set the debounce interval for saving and invalidateOnUnmount to invalidate the queries specified in invalidates prop on unmount. This feature is only available for the edit action. By default, autoSave is disabled.

const { onFinishAutoSave } = useForm({
  autoSave: {
    enabled: true, // default is false
    debounce: 2000, // debounce interval for auto-save, default is 1000
    invalidateOnUnmount: true, // whether to invalidate the queries on unmount, default is false
  },
});

In optimistic and undoable mutation modes, useForm will automatically update the query cache with the form values immediately after the mutation is triggered. This behavior can be customized for each query set (list, many and detail queries) using optimisticUpdateMap.

useForm({
    optimisticUpdateMap: {
        // A boolean value can also be used to enable/disable the optimistic updates for the query set.
        list: (
            previous, // Previous query data
            variables, // Variables used in the query
            id, // Record id
        ) => { ... },
        many: (
            previous, // Previous query data
            variables, // Variables used in the query
            id, // Record id
        ) => { ... },
        detail: (
            previous, // Previous query data
            variables, // Variables used in the query
        ) => { ... },
    }
})

A function to call to trigger the mutation. Depending on the action, it will trigger the mutation of useCreate or useUpdate hooks.

const { onFinish } = useForm({ ... });

return (
    <form onSubmit={() => onFinish(values)}>
        { /* ... */ }
    </form>
);

A function to call to trigger the auto-save mutation. It will trigger the mutation of useUpdate hook. This will not trigger the formLoading state.

const { onFinishAutoSave } = useForm({ ... });

React.useEffect(() => {
    // trigger auto-save on form values change, it will be debounced by the `autoSave.debounce` value
    onFinishAutoSave(values);
}, [values]);

A boolean value indicating the loading state of the form. It will reflect the loading status of the mutation or the query in edit and clone actions.

const { formLoading } = useForm({ ... });

Result of the mutation triggered by calling onFinish. Depending on the action, it will be the result of useCreate or useUpdate hooks.

const { mutationResult: { data, error, isLoading } } = useForm({ ... });

In edit and clone actions, result of the query of a record. It will be the result of useOne hook.

const { queryResult: { data, error, isLoading } } = useForm({ ... });

A setter function to set the id value. Useful when you want to change the id value after the form is mounted.

const { setId } = useForm({ ... });

const onItemSelect = (id) => {
    setId(id);
};

A function to handle custom redirections, it accepts redirect and id parameters. redirect can be list, edit, show, create or false. id is the record id if needed in the specified redirect route.

const { redirect } = useForm({ ... });

redirect("show", 123);

An object with elapsedTime value that can be used for the overtime loading feedback.

const { overtime: { elapsedTime } } = useForm({ ... });

An object with data, error and status values that can be used for the auto-save feedback. data will be the result of the auto-save mutation, error will be the error of the auto-save mutation and status will be the status of the auto-save mutation.

const { autoSaveProps: { data, error, status } } = useForm({ ... });