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 @pankod/refine-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.

create

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

http://localhost:3000

Live previews only work with the latest documentation.

import React from 'react'
import { IResourceComponentsProps } from '@pankod/refine-core'

import {
  List,
  Table,
  Form,
  Select,
  Input,
  Modal,
  Space,
  EditButton,
  useTable,
  useModalForm,
} from '@pankod/refine-antd'

const PostList: React.FC<IResourceComponentsProps> = () => {
  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'
}

edit

Let's learn how to add editing capabilities to records that will be opening form in Modal by using the action prop.

http://localhost:3000

Live previews only work with the latest documentation.

setInitialRoutes(['/posts'])

import React from 'react'
import { IResourceComponentsProps } from '@pankod/refine-core'

import {
  List,
  Table,
  Form,
  Select,
  Input,
  Modal,
  Space,
  EditButton,
  useTable,
  useModalForm,
} from '@pankod/refine-antd'

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

  const {
    modalProps: editModalProps,
    formProps: editFormProps,
    show: editModalShow,
  } = useModalForm<IPost>({
    action: 'edit',
    warnWhenUnsavedChanges: true,
  })

  return (
    <>
      <List>
        <Table {...tableProps} rowKey="id">
          <Table.Column dataIndex="id" title="ID" />
          <Table.Column dataIndex="title" title="Title" />
          <Table.Column dataIndex="status" title="Status" />
          <Table.Column<IPost>
            title="Actions"
            dataIndex="actions"
            key="actions"
            render={(_, record) => (
              <Space>
                <EditButton
                  hideText
                  size="small"
                  recordItemId={record.id}
                  onClick={() => editModalShow(record.id)}
                />
              </Space>
            )}
          />
        </Table>
      </List>
      <Modal {...editModalProps}>
        <Form {...editFormProps} 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'
}

caution

refine doesn't automatically add a <EditButton/> to the each record in <PostList> which opens edit form in <Modal> when clicked.

So, we have to put the <EditButton/> on our list. In that way, <Edit> form in <Modal> can fetch data by the record id.

<Table.Column<IPost>
  title="Actions"
  dataIndex="actions"
  key="actions"
  render={(_value, record) => <EditButton onClick={() => show(record.id)} />}
/>

caution

Don't forget to pass the record "id" to show to fetch the record data. This is necessary for both "edit" and "clone" forms.

clone

Let's learn how to add cloning capabilities to records that will be opening form in Modal by using the action prop.

http://localhost:3000

Live previews only work with the latest documentation.

setInitialRoutes(['/posts'])

import React from 'react'
import { IResourceComponentsProps } from '@pankod/refine-core'

import {
  List,
  Table,
  Form,
  Select,
  Input,
  Modal,
  Space,
  CloneButton,
  useTable,
  useModalForm,
} from '@pankod/refine-antd'

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

  const {
    modalProps: cloneModalProps,
    formProps: cloneFormProps,
    show: cloneModalShow,
  } = useModalForm<IPost>({
    action: 'clone',
  })

  return (
    <>
      <List>
        <Table {...tableProps} rowKey="id">
          <Table.Column dataIndex="id" title="ID" />
          <Table.Column dataIndex="title" title="Title" />
          <Table.Column dataIndex="status" title="Status" />
          <Table.Column<IPost>
            title="Actions"
            dataIndex="actions"
            key="actions"
            render={(_, record) => (
              <Space>
                <CloneButton
                  hideText
                  size="small"
                  recordItemId={record.id}
                  onClick={() => cloneModalShow(record.id)}
                />
              </Space>
            )}
          />
        </Table>
      </List>
      <Modal {...cloneModalProps}>
        <Form {...cloneFormProps} 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'
}

caution

refine doesn't automatically add a <CloneButton/> to the each record in <PostList> which opens clone form in <Modal> when clicked.

So, we have to put the <CloneButton/> on our list. In that way, <Clone> form in <Modal> can fetch data by the record id.

<Table.Column<IPost>
  title="Actions"
  dataIndex="actions"
  key="actions"
  render={(_value, record) => <CloneButton onClick={() => show(record.id)} />}
/>

caution

Don't forget to pass the record id to show to fetch the record data. This is necessary for both "edit" and "clone" forms.

Properties

tip

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

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.

Return Value

Key	Description	Type
show	A function that can open the modal	(id?: BaseKey) => void
formProps	Props needed to manage form component	FormProps
modalProps	Props for needed to manage modal component	ModalProps
formLoading	Loading status of form	boolean
submit	Submit method, the parameter is the value of the form fields	() => void
open	Whether the modal dialog is open or not	boolean
close	Specify a function that can close the modal	() => void
defaultFormValuesLoading	DefaultFormValues loading status of form	boolean
form	Ant Design form instance	FormInstance<TVariables>
id	Record id for edit action	BaseKey | undefined
setId	id setter	Dispatch<SetStateAction< BaseKey | undefined>>
queryResult	Result of the query of a record	QueryObserverResult<{ data: TData }>
mutationResult	Result of the mutation triggered by submitting the form	UseMutationResult< { data: TData }, TError, { resource: string; values: TVariables; }, unknown>

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

Example

VIEW SOURCE CODE →

RUN IN YOUR LOCAL

npm create refine-app@latest -- --example form-antd-use-modal-form