useForm

useForm is a hook that allows to manage forms. It has some action methods that create, edit and clone the form. The hook return value comes to according to the called action and it can run different logic depending on the action.

info

If you're looking for a complete form library, Refine supports two form libraries out-of-the-box.

• React Hook Form (for Headless users) - Documentation - Example
• Ant Design Form (for Ant Design users) - Documentation - Example
• Mantine Form (for Mantine users) - Documentation - Example

Basic Usage

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

src/posts/create.tsx

import { useState } from "react";
import { useForm } from "@pankod/refine-core";

export const PostCreate = () => {
    const [title, setTitle] = useState();
    const { onFinish } = useForm({
        action: "create",
    });

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

    return (
        <form onSubmit={onSubmit}>
            <input onChange={(e) => setTitle(e.target.value)} />
            <button type="submit">Submit</button>
        </form>
    );
};

• Returns the mutationResult after called the onFinish callback.
• Accepts generic type parameters. It is used to define response type of the mutation and query.

Actions

useForm can handle edit, create and clone actions.

tip

By default, it determines the action from route. In the above example, the route is /posts/create thus the hook will be called with action: "create". If the route is /posts/edit/1, the hook will be called with action: "edit".

It can be overridden by passing the action prop where it isn't possible to determine the action from the route (e.g. when using form in a modal or using a custom route).

action: "edit"

action: "edit" is used for editing an existing record. It requires the id for determining the record to edit. By default, it uses the id from the route. It can be changed with the setId function or id property.

It fetches the record data according to the id and returns the queryResult for you to fill the form.

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.

action: "clone"

action: "clone" is used for cloning an existing record. It requires the id for determining the record to clone. By default, it uses the id from the route. It can be changed with the setId function.

It fetches the record data according to the id and returns the queryResult for you to fill the form.

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

API Reference

Properties

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

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.	{}

Return values

Property	Description	Type
onFinish	Triggers the mutation	(values: TVariables) => Promise<CreateResponse<TData> | UpdateResponse<TData> | void>
queryResult	Result of the query of a record	QueryObserverResult<T>
mutationResult	Result of the mutation triggered by calling onFinish	UseMutationResult<T>
formLoading	Loading state of form request	boolean
id	Record id for clone and create action	BaseKey
setId	id setter	Dispatch<SetStateAction< string | number | undefined>>
redirect	Redirect function for custom redirections	(redirect: "list"|"edit"|"show"|"create"| false ,idFromFunction?: BaseKey|undefined) => data

useModal hook allows you to manage a modal. Since it is designed as headless, it only outputs show and close functions and visible for state. It expects you to handle the UI.

You can use the visible state to show or hide the modal.