useForm

useForm is used to manage forms. It uses Ant Design Form data scope management under the hood and returns the required props for managing the form actions.

Usage

We'll show the basic usage of useForm by adding an editing form.

pages/posts/edit.tsx

import { Edit, Form, Input, useForm, Select } from "@pankod/refine";

export const PostEdit: React.FC = () => {
    const { formProps, saveButtonProps } = useForm<IPost>();

    return (
        <Edit saveButtonProps={saveButtonProps}>
            <Form {...formProps} layout="vertical">
                <Form.Item label="Title" name="title">
                    <Input />
                </Form.Item>
                <Form.Item label="Status" name="status">
                    <Select
                        options={[
                            {
                                label: "Published",
                                value: "published",
                            },
                            {
                                label: "Draft",
                                value: "draft",
                            },
                            {
                                label: "Rejected",
                                value: "rejected",
                            },
                        ]}
                    />
                </Form.Item>
            </Form>
        </Edit>
    );
};

interface IPost {
    id: string;
    title: string;
    status: "published" | "draft" | "rejected";
}

const { formProps, saveButtonProps } = useForm<IPost>();

formProps includes all necessary values to manage Ant Design Form components.

In the example if you navigate to /posts/edit/1234 it will manage the data of the post with id of 1234 in an editing context. See Actions on how useForm determines this is an editing context.

Since this is an edit form it will fill the form with the data of the post with id of 1234 and then the form will be ready to edit further and submit the changes.

Submit functionality is provided by saveButtonProps which includes all of the necessary props for a button to submit a form including automatically updating loading states.

useForm accepts type parameters for the record in use and for the response type of the mutation. IPost in the example represents the record to edit. It is also used as the default type for mutation response.

Actions

useForm can handle edit, create and clone actions.

tip

By default it determines the action from route. In the example, the route is /posts/edit/1234 thus this is an editing form.

It can take an action parameter for the situations where it isn't possible to determine the action from route i.e. using a form in a modal, using a custom route.

const { formProps, saveButtonProps } = useForm({ action: "edit" });

action: "edit"

action: "edit" is used for editing an existing record. Form will initially be filled with the data of the record.

useForm uses useUpdate under the hood for mutations on edit mode.

action: "create"

action: "create"is used for creating a new record that didn't exist before.

useForm uses useCreate under the hood for mutations on create mode.

Clone mode

When creating a new record, useForm can initialize the form with the data of an existing record.

useForm works on clone mode when a route has a clone and id parameters like this {{resourceName}}/clone/1234. Alternatively, if route doesn't have those parameters, action can be set with action: "clone" and id can be set with setCloneId.

const { setCloneId } = useForm();

tip

If you want to show a form in a modal or drawer where necessary route params might not be there you can use the useModalForm or the useDrawerForm hook.

tip

<CloneButton> can be used to navigate to a clone route with an id like this {{resourceName}}/clone/1234.

<CloneButton recordItemId={record.id} />

Also the clone method from the useNavigation hook can be used as well.

const { clone } = useNavigation();

<Button onClick={() => clone("posts", record.id)} />

API Reference

Properties

Property	Description	Type	Default
action	Type of the form mode	"edit" | "create"
resource	Resource name for API data interactions	string
onMutationSuccess	Called when a mutation is successful	(data: UpdateResponse<M>, variables: any, context: any) => void
onMutationError	Called when a mutation encounters an error	(error: any, variables: any, context: any) => void
mutationMode	Determines when mutations are executed	"pessimistic | "optimistic | "undoable"	"pessimistic"*
submitOnEnter	Listens Enter key press to submit form	boolean	false
warnWhenUnsavedChanges	Shows notification when unsaved changes exist	boolean	false*
redirect	Page to redirect after a succesfull mutation	"show | "edit | "list" | false	"list"
undoableTimeout	Duration to wait before executing mutations when mutationMode = "undoable"	number	5000*
successNotification	Successful Mutation notification	SuccessErrorNotification	"Successfully created resource" or "Successfully updated resource"
errorNotification	Unsuccessful Mutation notification	SuccessErrorNotification	"There was an error creating resource (status code: statusCode)" or "Error when updating resource (status code: statusCode)"
metaData	Metadata query for dataProvider	MetaDataQuery	{}
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.	"auto" | "manual" | "off"	"off"
liveParams	Params to pass to liveProvider's subscribe method if liveMode is enabled.	{ ids?: string[]; [key: string]: any; }	undefined
onLiveEvent	Callback to handle all related live events of this hook.	(event: LiveEvent) => void	undefined

*: 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.

Return values

Property	Description	Type
form	Ant Design form instance	FormInstance
formProps	Ant Design form props	FormProps
saveButtonProps	Props for a submit button	{ disabled: boolean; onClick: () => void; loading?:boolean; }
queryResult	Result of the query of a record	QueryObserverResult<T>
mutationResult	Result of the mutation triggered by submitting the form	UseMutationResult<T>
formLoading	Loading state of form request	boolean
cloneId	Record id for clone action	"string" | "number"
setCloneId	cloneId setter	Dispatch<SetStateAction< string | number | undefined>>
editId	Record id for edit action	"string" | "number"
setEditId	editId setter	Dispatch<SetStateAction< string | number | undefined>>

Type Parameters

Property	Desription	Default
TData	Result data of the query that extends BaseRecord	BaseRecord
TError	Custom error object that extends HttpError	HttpError
TVariables	Values for params.	{}

Live Codesandbox Example