Skip to main content
Version: 4.xx.xx

useModalForm

useModalForm hook allows you to manage a form within a <Modal>. It returns Ant Design <Form> and Modal components props.

info

useModalForm hook is extended from useForm from the @refinedev/antd package. This means that you can use all the features of useForm hook.

Basic Usage

We'll show three examples, "create", "edit" and "clone". Let's see how useModalForm is used in all.

In this example, we will show you how to create a record with useModalForm.

http://localhost:3000
import React from "react";

import { List, EditButton, useTable, useModalForm } from "@refinedev/antd";
import { Table, Form, Select, Input, Modal, Space } from "antd";

const PostList: React.FC = () => {
const { tableProps } = useTable<IPost>();

const {
modalProps: createModalProps,
formProps: createFormProps,
show: createModalShow,
} = useModalForm<IPost>({
action: "create",
});

return (
<>
<List
// createButtonProps allows us to create and manage a button above the table.
// This code block makes <Modal> appear when you click the button.
createButtonProps={{
onClick: () => {
createModalShow();
},
}}
>
<Table {...tableProps} rowKey="id">
<Table.Column dataIndex="id" title="ID" />
<Table.Column dataIndex="title" title="Title" />
<Table.Column dataIndex="status" title="Status" />
</Table>
</List>
<Modal {...createModalProps}>
<Form {...createFormProps} layout="vertical">
<Form.Item
label="Title"
name="title"
rules={[
{
required: true,
},
]}
>
<Input />
</Form.Item>
<Form.Item
label="Status"
name="status"
rules={[
{
required: true,
},
]}
>
<Select
options={[
{
label: "Published",
value: "published",
},
{
label: "Draft",
value: "draft",
},
{
label: "Rejected",
value: "rejected",
},
]}
/>
</Form.Item>
</Form>
</Modal>
</>
);
};

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

Properties

tip

All useForm props also available in useModalForm. You can find descriptions on useForm docs.

syncWithLocation

Default: false

When true, the modals visibility state and the id of the record will be synced with the URL.

This property can also be set as an object { key: string; syncId?: boolean } to customize the key of the URL query parameter. id will be synced with the URL only if syncId is true.

const modalForm = useModalForm({
syncWithLocation: { key: "my-modal", syncId: true },
});

defaultFormValues

Only available in "create" form.

Default values for the form. Use this to pre-populate the form with data that needs to be displayed.

const modalForm = useModalForm({
defaultFormValues: {
title: "Hello World",
},
});

defaultVisible

Default: false

When true, modal will be visible by default.

const modalForm = useModalForm({
defaultVisible: true,
});

autoSubmitClose

Default: true

When true, modal will be closed after successful submit.

const modalForm = useModalForm({
autoSubmitClose: false,
});

autoResetForm

Default: true

When true, form will be reset after successful submit.

const modalForm = useModalForm({
autoResetForm: false,
});

warnWhenUnsavedChanges

Default: false

When you have unsaved changes and try to leave the current page, refine shows a confirmation modal box. To activate this feature.

You can also set this value in <Refine> component.

const modalForm = useModalForm({
warnWhenUnsavedChanges: true,
});

Return Values

formProps

It's required to manage <Form> state and actions. Under the hood the formProps came from useForm.

It contains the props to manage the Antd <Form> component such as onValuesChange, initialValues, onFieldsChange, onFinish etc.

modalProps

The props needed by the <Modal> component.

title

Default when url is "/posts/create": "Create Post"

Title of the modal. Value is based on resource and action values.

okText

Default: "Save"

Text of the "submit" button within the modal.

cancelText

Default: "Cancel"

Text of the "cancel" button within the modal.

width

Default: 1000px

Width of the <Modal>

forceRender

Default: true

It renders <Modal> instead of lazy rendering it.

okButtonProps

It contains all the props needed by the "submit" button within the modal (disabled,loading etc.). When okButtonProps.onClick is called, it triggers form.submit(). You can manually pass these props to your custom button.

onOk

A function that can submit the <Form> inside <Modal>. It's useful when you want to submit the form manually.

onCancel

Same as close

A function that can close the <Modal>. It's useful when you want to close the modal manually.

visible

@deprecated. Please use open instead.

Current visible state of <Modal>. Default value depends on defaultVisible prop.

open

Current visible state of <Modal>. Default value depends on defaultVisible prop.

close

Same as onCancel

A function that can close the modal. It's useful when you want to close the modal manually.

const { close, modalProps, formProps, onFinish } = useModalForm();

const onFinishHandler = (values) => {
onFinish(values);
close();
};

// ---

return (
<Modal {...modalProps}>
<Form {...formProps} onFinish={onFinishHandler} layout="vertical">
<Form.Item label="Title" name="title">
<Input />
</Form.Item>
</Form>
</Modal>
);

submit

A function that can submit the form. It's useful when you want to submit the form manually.

const { modalProps, formProps, submit } = useModalForm();

// ---

return (
<Modal
{...modalProps}
footer={[
<Button key="submit" type="primary" onClick={submit}>
Submit
</Button>,
]}
>
<Form {...formProps} layout="vertical">
<Form.Item label="Title" name="title">
<Input />
</Form.Item>
</Form>
</Modal>
);

show

A function that can show the modal.

const { modalProps, formProps, show } = useModalForm();

return (
<>
<Button type="primary" onClick={() => show()}>
Show Modal
</Button>
<Modal
{...modalProps}
footer={[
<Button key="submit" type="primary" onClick={submit}>
Submit
</Button>,
]}
>
<Form {...formProps} onFinish={onFinishHandler} layout="vertical">
<Form.Item label="Title" name="title">
<Input />
</Form.Item>
</Form>
</Modal>
</>
);
const { modalProps, formProps } = useModalForm();

// ---

return (
<Modal
{...modalProps}
footer={
<Button
onClick={(
e: React.MouseEvent<HTMLAnchorElement, MouseEvent> &
React.MouseEvent<HTMLButtonElement, MouseEvent>,
) => modalProps.onCancel(e)}
>
Cancel
</Button>
}
>
<Form {...formProps} layout="vertical">
<Form.Item label="Title" name="title">
<Input />
</Form.Item>
</Form>
</Modal>
);

API Reference

Properties

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

**: If not explicitly configured, default value of redirect depends on which action used. If action is create, redirects default value is edit (created resources edit page). If action is edit instead, redirects default value is list.

Type Parameters

PropertyDesriptionTypeDefault
TDataResult data returned by the query function. Extends BaseRecordBaseRecordBaseRecord
TErrorCustom error object that extends HttpErrorHttpErrorHttpError
TVariablesValues for params.{}
TSelectDataResult data returned by the select function. Extends BaseRecord. If not specified, the value of TData will be used as the default value.BaseRecordTData

Return Value

KeyDescriptionType
showA function that can open the modal(id?: BaseKey) => void
formPropsProps needed to manage form componentFormProps
modalPropsProps for needed to manage modal componentModalProps
formLoadingLoading status of formboolean
submitSubmit method, the parameter is the value of the form fields() => void
openWhether the modal dialog is open or notboolean
closeSpecify a function that can close the modal() => void
defaultFormValuesLoadingDefaultFormValues loading status of formboolean
formAnt Design form instanceFormInstance<TVariables>
idRecord id for edit actionBaseKey | undefined
setIdid setterDispatch<SetStateAction< BaseKey | undefined>>
queryResultResult of the query of a recordQueryObserverResult<{ data: TData }>
mutationResultResult of the mutation triggered by submitting the formUseMutationResult<
{ data: TData },
TError,
{ resource: string; values: TVariables; },
unknown>

Example

RUN IN YOUR LOCAL
npm create refine-app@latest -- --example form-antd-use-modal-form