Skip to main content
Version: 4.xx.xx
Source Code

useForm

A hook that orchestrates Refine's data hooks to create, edit, and clone data. It also provides a set of features to make it easier for users to implement their real world needs and handle edge cases such as redirects, invalidation, auto-save and more.

import { useForm } from "@refinedev/core";

const { onFinish, ... } = useForm({ ... });
Extended Versions:

@refinedev/antd, @refinedev/mantine and @refinedev/react-hook-form packages provide their own extended versions of useForm hook with full support for their respective form implementations including validation, error handling, form values, and more.

Refer to their respective documentation for more information and check out the Forms in Refine guide for detailed information on how to handle forms in Refine.

Usage

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

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;
}

Parameters

action
Router Integrated
This value can be inferred from the route. Click to see the guide for more information.

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" });

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.

Edit

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.

Clone

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.

resource
Check the guide
Please check the guide for more information on this topic.
Router Integrated
This value can be inferred from the route. Click to see the guide for more information.

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" });

id
Router Integrated
This value can be inferred from the route. Click to see the guide for more information.

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,
});
Using with explicit resource:

If explicit resource is provided, id must be provided as well to avoid any unexpected API calls.

redirect
Check the guide
Please check the guide for more information on this topic.
Globally Configurable
This value can be configured globally. Click to see the guide for more information.

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" });
Router Integration:

This will only work if you have routerProvider defined in your <Refine> component along with the proper resource definition with routes and actions.

onMutationSuccess

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
) => { ... }
});

onMutationError

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
) => { ... }
});

invalidates
Check the guide
Please check the guide for more information on this topic.

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"] });

dataProviderName
Globally Configurable
This property can also be included in the `resource` definition.

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

useForm({ dataProviderName: "store" });

mutationMode
Check the guide
Please check the guide for more information on this topic.
Globally Configurable
This value can be configured globally. Click to see the guide for more information.

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" });

successNotification
Check the guide
Please check the guide for more information on this topic.

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",
};
},
});

errorNotification
Check the guide
Please check the guide for more information on this topic.

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",
};
},
});

meta
Check the guide
To learn more about the `meta` and how it works with the data providers, refer to General Concepts guide

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" } } });

queryMeta

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" } } });

mutationMeta

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" } } });

queryOptions

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

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

createMutationOptions

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

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

updateMutationOptions

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

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

liveMode
Check the guide
Please check the guide for more information on this topic.

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" });

onLiveEvent
Check the guide
Please check the guide for more information on this topic.

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

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

liveParams

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

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

overtimeOptions

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);
},
});

autoSave
Check the guide
Please check the guide for more information on this topic.

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
},
});
Auto-save Implementation:

Core implementation of the useForm hook doesn't provide out of the box auto-save functionality since it doesn't have access to the form values but it provides the necessary props and callbacks to implement it.

Extended versions of useForm (such as the one in @refinedev/react-hook-form) provides auto-save functionality out of the box.

optimisticUpdateMap
Check the guide
Please check the guide for more information on this topic.

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
) => { ... },
}
})

Return Values

onFinish

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>
);

onFinishAutoSave

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]);

formLoading

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({ ... });

mutation

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

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

query

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

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

setId

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);
};

redirect
Check the guide
Please check the guide for more information on this topic.

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);

overtime

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

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

autoSaveProps

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({ ... });

mutationResult
deprecated

This prop is deprecated and will be removed in the future versions. Use mutation instead.

queryResult
deprecated

This prop is deprecated and will be removed in the future versions. Use query instead.

API Reference

Properties

PropertyTypeDescriptionDefault
resource

string

Resource name for API data interactions

Resource name that it reads from route

id

Record id for fetching

Id that it reads from the URL

redirect

"show" | "edit" | "list" | "create" | false

Page to redirect after a succesfull mutation

"list"

meta

MetaQuery

Metadata query for dataProvider

metaData

metaData is deprecated with refine@4, refine will pass meta instead, however, we still support metaData for backward compatibility.

MetaQuery

Metadata query for dataProvider

queryMeta

MetaQuery

Metadata to pass for the useOne query

mutationMeta

MetaQuery

Metadata to pass for the mutation (useCreate for create and clone actions, useUpdate for edit action)

mutationMode

"pessimistic" | "optimistic" | "undoable"

Determines when mutations are executed

"pessimistic"*

onMutationSuccess

((data: UpdateResponse<TResponse>

CreateResponse<TResponse>, variables: TVariables, context: any, isAutoSave?: boolean) => void)

Called when a mutation is successful

onMutationError

((error: TResponseError, variables: TVariables, context: any, isAutoSave?: boolean) => void)

Called when a mutation encounters an error

undoableTimeout

number

Duration to wait before executing mutations when mutationMode = "undoable"

5000*

dataProviderName

string

If there is more than one dataProvider, you should use the dataProviderName that you will use.

invalidates

all, resourceAll, list, many, detail, false

You can use it to manage the invalidations that will occur at the end of the mutation.

["list", "many", "detail"]

queryOptions

UseQueryOptions<GetOneResponse<TQueryFnData>, TError, GetOneResponse<TData>, QueryKey>

react-query's useQuery options of useOne hook used while in edit mode.

createMutationOptions

Omit<UseMutationOptions<CreateResponse<TResponse>, TResponseError, UseCreateParams<TResponse, TResponseError, TVariables>, unknown>, "mutationFn">

react-query's useMutation options of useCreate hook used while submitting in create and clone modes.

updateMutationOptions

Omit<UseMutationOptions<UpdateResponse<TResponse>, TResponseError, UpdateParams<TResponse, TResponseError, TVariables>, PrevContext<...>>, "mutationFn"

"onMutate">

react-query's useMutation options of useUpdate hook used while submitting in edit mode.

optimisticUpdateMap

OptimisticUpdateMapType<TResponse, TVariables>

If you customize the optimisticUpdateMap option, you can use it to manage the invalidations that will occur at the end of the mutation.

{ list: true, many: true, detail: true, }

successNotification

false

OpenNotificationParams

((data?: UpdateResponse<TResponse>

CreateResponse<TResponse>, values?: TVariables

... 1 more ..., resource?: string

undefined) => false

OpenNotificationParams)

undefined

Success notification configuration to be displayed when the mutation is successful.

'"There was an error creating resource (status code: statusCode)" or "Error when updating resource (status code: statusCode)"'

errorNotification

false

OpenNotificationParams

((error?: TResponseError, values?: TVariables

{ id: BaseKey; values: TVariables; }, resource?: string

undefined) => false

OpenNotificationParams)

undefined

Error notification configuration to be displayed when the mutation fails.

'"There was an error creating resource (status code: statusCode)" or "Error when updating resource (status code: statusCode)"'

action

"create" | "edit" | "clone"

Type of the form mode

Action that it reads from route otherwise "create" is used

liveMode

Whether to update data automatically ("auto") or not ("manual") if a related live event is received. The "off" value is used to avoid creating a subscription.

"off"

onLiveEvent

Callback to handle all related live events of this hook.

undefined

liveParams

Params to pass to liveProvider's subscribe method if liveMode is enabled.

undefined

overtimeOptions

UseLoadingOvertimeCoreOptions

autoSave

{ enabled: boolean; debounce?: number; onFinish?: ((values: TVariables) => TVariables); invalidateOnUnmount?: boolean

undefined; invalidateOnClose?: boolean

undefined; }

undefined

Global Configuration:

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

Type Parameters

PropertyDescriptionTypeDefault
TQueryFnDataResult data returned by the query function. Extends [BaseRecord][baserecord][BaseRecord][baserecord][BaseRecord][baserecord]
TErrorCustom error object that extends [HttpError][httperror][HttpError][httperror][HttpError][httperror]
TVariablesValues for params.{}
TDataResult data returned by the select function. Extends [BaseRecord][baserecord]. If not specified, the value of TQueryFnData will be used as the default value.[BaseRecord][baserecord]TQueryFnData
TResponseResult data returned by the mutation function. Extends [BaseRecord][baserecord]. If not specified, the value of TData will be used as the default value.[BaseRecord][baserecord]TData
TResponseErrorCustom error object that extends [HttpError][httperror]. If not specified, the value of TError will be used as the default value.[HttpError][httperror]TError

Return values

PropertyDescriptionType
onFinishTriggers the mutation(values: TVariables) => Promise<CreateResponse<TData> | UpdateResponse<TData> | void>
queryResult of the query of a recordQueryObserverResult<TData, TError>
mutationResult of the mutation triggered by calling onFinishUseMutationResult<T>
formLoadingLoading state of form requestboolean
idRecord id for clone and create actionBaseKey
setIdid setterDispatch<SetStateAction< string | number | undefined>>
redirectRedirect function for custom redirections(redirect: "list"|"edit"|"show"|"create"| false ,idFromFunction?: BaseKey|undefined) => data
overtimeOvertime loading props{ elapsedTime?: number }
autoSavePropsAuto save props{ data: UpdateResponse<TData> | undefined, error: HttpError | null, status: "loading" | "error" | "idle" | "success" }