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​

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