useModalForm
useModalForm
hook also allows you to manage a form inside a modal component. It provides some useful methods to handle the form modal.
useModalForm
hook is extended from useForm
hook from the @refinedev/mantine
package. This means that you can use all the features of useForm
hook.
Basic Usage
We will show three examples, "create"
, "edit"
and "clone"
. Let's see how useModalForm
is used in all.
- create
- edit
- clone
In this example, we will show you how to "create"
a record with useModalForm
:
In this example, we will show you how to "edit"
a record with useModalForm
:
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 for "edit"
form in <Modal>
to be able to fetch data by the record id
.
const columns = React.useMemo<ColumnDef<IPost>[]>(
() => [
// --
{
id: "actions",
header: "Actions",
accessorKey: "id",
enableColumnFilter: false,
enableSorting: false,
cell: function render({ getValue }) {
return (
<Group spacing="xs" noWrap>
<EditButton
hideText
onClick={() => show(getValue() as number)}
/>
</Group>
);
},
},
],
[],
);
const table = useTable({
columns,
});
Don't forget to pass the record "id"
to show
to fetch the record data. This is necessary for both "edit"
and "clone"
forms.
In this example, we will show you how to "clone"
a record with useModalForm
.
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 for "clone"
form in <Modal>
to be able to fetch data by the record id
.
const columns = React.useMemo<ColumnDef<IPost>[]>(
() => [
// --
{
id: "actions",
header: "Actions",
accessorKey: "id",
enableColumnFilter: false,
enableSorting: false,
cell: function render({ getValue }) {
return (
<Group spacing="xs" noWrap>
<CloneButton
hideText
onClick={() => show(getValue() as number)}
/>
</Group>
);
},
},
],
[],
);
const table = useTable({
columns,
});
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
refineCoreProps
All useForm
properties are also available in useStepsForm
. You can find descriptions on useForm
documentation.
const modalForm = useModalForm({
refineCoreProps: {
action: "edit",
resource: "posts",
id: "1",
},
});
initialValues
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({
initialValues: {
title: "Hello World",
},
});
defaultVisible
When true
, modal will be visible by default. It is false
by default.
const modalForm = useModalForm({
modalProps: {
defaultVisible: true,
},
});
autoSubmitClose
When true
, modal will be closed after successful submit. It is true
by default.
const modalForm = useModalForm({
modalProps: {
autoSubmitClose: false,
},
});
autoResetForm
When true
, form will be reset after successful submit. It is true
by default.
const modalForm = useModalForm({
modalProps: {
autoResetForm: false,
},
});
syncWithLocation
When true
, the modals visibility state and the id
of the record will be synced with the URL. It is false
by default.
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 },
});
overtimeOptions
If you want loading overtime for the request, you can pass the overtimeOptions
prop to the this hook. It is useful when you want to show a loading indicator when the request takes too long.
interval
is the time interval in milliseconds. onInterval
is the function that will be called on each interval.
Return overtime
object from this hook. elapsedTime
is the elapsed time in milliseconds. It becomes undefined
when the request is completed.
const { overtime } = useModalForm({
//...
overtimeOptions: {
interval: 1000,
onInterval(elapsedInterval) {
console.log(elapsedInterval);
},
},
});
console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
// You can use it like this:
{
elapsedTime >= 4000 && <div>this takes a bit longer than expected</div>;
}
autoSave
If you want to save the form automatically after some delay when user edits the form, you can pass true to autoSave.enabled
prop.
By default the autoSave
feature does not invalidate queries. However, you can use the invalidateOnUnmount
and invalidateOnClose
props to invalidate queries upon unmount or close.
It also supports onMutationSuccess
and onMutationError
callback functions. You can use isAutoSave
parameter to determine whether the mutation is triggered by autoSave
or not.
autoSave
feature operates exclusively in edit
mode. Users can take advantage of this feature while editing data, as changes are automatically saved in editing mode. However, when creating new data, manual saving is still required.
onMutationSuccess
and onMutationError
callbacks will be called after the mutation is successful or failed.
enabled
Default:
false
To enable the autoSave
feature, set the enabled
parameter to true
.
useModalForm({
refineCoreProps: {
autoSave: {
enabled: true,
},
},
});
debounce
Default:
1000
Set the debounce time for the autoSave
prop.
useModalForm({
refineCoreProps: {
autoSave: {
enabled: true,
debounce: 2000,
},
},
});
invalidateOnUnmount
Default:
false
This prop is useful when you want to invalidate the list
, many
and detail
queries from the current resource when the hook is unmounted. By default, it invalidates the list
, many
and detail
queries associated with the current resource. Also, You can use the invalidates
prop to select which queries to invalidate.
useModalForm({
refineCoreProps: {
autoSave: {
enabled: true,
invalidateOnUnmount: true,
},
},
});
invalidateOnClose
Default:
false
This prop is useful when you want to invalidate the list
, many
and detail
queries from the current resource when the modal is closed. By default, it invalidates the list
, many
and detail
queries associated with the current resource. Also, You can use the invalidates
prop to select which queries to invalidate.
useModalForm({
refineCoreProps: {
autoSave: {
enabled: true,
invalidateOnClose: true,
},
},
});
Return Values
All useForm
return values also available in useModalForm
. You can find descriptions on useForm
docs.
All mantine useForm
return values also available in useModalForm
. You can find descriptions on mantine
docs.
visible
Current visibility state of the modal.
const modalForm = useModalForm({
defaultVisible: true,
});
console.log(modalForm.modal.visible); // true
title
Title of the modal. Based on resource and action values
const {
modal: { title },
} = useModalForm({
refineCoreProps: {
resource: "posts",
action: "create",
},
});
console.log(title); // "Create Post"
close
A function that can close the modal. It's useful when you want to close the modal manually.
const {
getInputProps,
modal: { close, visible, title },
} = useModalForm();
return (
<Modal opened={visible} onClose={close} title={title}>
<TextInput
mt={8}
label="Title"
placeholder="Title"
{...getInputProps("title")}
/>
<Box mt={8} sx={{ display: "flex", justifyContent: "flex-end" }}>
<SaveButton {...saveButtonProps} />
<Button onClick={close}>Cancel</Button>
</Box>
</Modal>
);
submit
submit
is a function that can submit the form. It's useful when you want to submit the form manually.
const {
modal: { submit },
} = useModalForm();
// ---
return (
<Modal opened={visible} onClose={close} title={title}>
<TextInput
mt={8}
label="Title"
placeholder="Title"
{...getInputProps("title")}
/>
<Box mt={8} sx={{ display: "flex", justifyContent: "flex-end" }}>
<Button onClick={submit}>Save</Button>
</Box>
</Modal>
);
show
show
is a function that can show the modal.
const {
getInputProps,
modal: { close, visible, title, show },
} = useModalForm();
const onFinishHandler = (values) => {
onFinish(values);
show();
};
return (
<>
<Button onClick={}>Show Modal</Button>
<Modal opened={visible} onClose={close} title={title}>
<TextInput
mt={8}
label="Title"
placeholder="Title"
{...getInputProps("title")}
/>
<Box mt={8} sx={{ display: "flex", justifyContent: "flex-end" }}>
<SaveButton {...saveButtonProps} />
</Box>
</Modal>
</>
);
saveButtonProps
saveButtonProps
contains all the props needed by the "submit" button within the modal (disabled,loading etc.). You can manually pass these props to your custom button.
const { getInputProps, modal, saveButtonProps } = useModalForm();
return (
<Modal {...modal}>
<TextInput
mt={8}
label="Title"
placeholder="Title"
{...getInputProps("title")}
/>
<Box mt={8} sx={{ display: "flex", justifyContent: "flex-end" }}>
<Button
{...saveButtonProps}
onClick={(e) => {
// -- your custom logic
saveButtonProps.onClick(e);
}}
/>
</Box>
</Modal>
);
overtime
overtime
object is returned from this hook. elapsedTime
is the elapsed time in milliseconds. It becomes undefined
when the request is completed.
const { overtime } = useModalForm();
console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
autoSaveProps
If autoSave
is enabled, this hook returns autoSaveProps
object with data
, error
, and status
properties from mutation.
FAQ
How can I change the form data before submitting it to the API?
You may need to modify the form data before it is sent to the API.
For example, let's send the values we received from the user in two separate inputs, name
and surname
, to the API as fullName
.
import React from "react";
import { useModalForm } from "@refinedev/mantine";
import { TextInput, Modal } from "@mantine/core";
const UserCreate: React.FC = () => {
const {
getInputProps,
saveButtonProps,
modal: { show, close, title, visible },
} = useModalForm({
refineCoreProps: { action: "create" },
initialValues: {
name: "",
surname: "",
},
transformValues: (values) => ({
fullName: `${values.name} ${values.surname}`,
}),
});
return (
<Modal opened={visible} onClose={close} title={title}>
<TextInput
mt={8}
label="Name"
placeholder="Name"
{...getInputProps("name")}
/>
<TextInput
mt={8}
label="Surname"
placeholder="Surname"
{...getInputProps("surname")}
/>
<Box mt={8} sx={{ display: "flex", justifyContent: "flex-end" }}>
<Button
{...saveButtonProps}
onClick={(e) => {
// -- your custom logic
saveButtonProps.onClick(e);
}}
/>
</Box>
</Drawer>
);
};
API Reference
Properties
Property | Description | Type |
---|---|---|
modalProps | Configuration object for the modal or drawer | ModalPropsType |
refineCoreProps | Configuration object for the core of the useForm | UseFormProps |
@mantine/form 's useForm properties | See useForm documentation |
ModalPropsType
Property Description Type Default defaultVisible Initial visibility state of the modal boolean
false
autoSubmitClose Whether the form should be submitted when the modal is closed boolean
true
autoResetForm Whether the form should be reset when the form is submitted boolean
true
Type Parameters
Property | Desription | Type | Default |
---|---|---|---|
TQueryFnData | Result data returned by the query function. Extends BaseRecord | BaseRecord | BaseRecord |
TError | Custom error object that extends HttpError | HttpError | HttpError |
TVariables | Form values for mutation function | {} | Record<string, unknown> |
TTransformed | Form values after transformation for mutation function | {} | TVariables |
TData | Result data returned by the select function. Extends BaseRecord . If not specified, the value of TQueryFnData will be used as the default value. | BaseRecord | TQueryFnData |
TResponse | Result data returned by the mutation function. Extends BaseRecord . If not specified, the value of TData will be used as the default value. | BaseRecord | TData |
TResponseError | Custom error object that extends HttpError . If not specified, the value of TError will be used as the default value. | HttpError | TError |
Return values
Property | Description | Type |
---|---|---|
modal | Relevant states and methods to control the modal or drawer | ModalReturnValues |
refineCore | The return values of the useForm in the core | UseFormReturnValues |
@mantine/form 's useForm return values | See useForm documentation | |
overtime | Overtime loading props | { elapsedTime?: number } |
autoSaveProps | Auto save props | { data: UpdateResponse<TData> | undefined, error: HttpError | null, status: "loading" | "error" | "idle" | "success" } |
ModalReturnValues
Property Description Type visible State of modal visibility boolean
show Sets the visible state to true (id?: BaseKey) => void
close Sets the visible state to false () => void
submit Submits the form (values: TVariables) => void
title Modal title based on resource and action value string
saveButtonProps Props for a submit button { disabled: boolean, onClick: (e: React.FormEvent<HTMLFormElement>) => void; }
Example
npm create refine-app@latest -- --example form-mantine-use-modal-form
- Basic Usage
- Properties
refineCoreProps
initialValues
defaultVisible
autoSubmitClose
autoResetForm
syncWithLocation
overtimeOptions
autoSave
enabled
debounce
invalidateOnUnmount
invalidateOnClose
- Return Values
visible
title
close
submit
show
saveButtonProps
overtime
autoSaveProps
- FAQ
- How can I change the form data before submitting it to the API?
- API Reference
- Properties
- Type Parameters
- Return values
- Example