Form actions

Change form state from anywhere in the application

Docs

Package

Usage

Form actions allow changing state of the form from anywhere in your application. The mechanism of form actions is similar to notifications system, modals manager and other similar packages.

To use form actions, set name property in use-form settings:

import { useForm } from '@mantine/form';

export interface DemoFormValues {
  name: string;
  age: number;
}

function Demo() {
  const form = useForm<DemoFormValues>({
    mode: 'uncontrolled',
    name: 'demo-form',
    initialValues: {
      name: '',
      age: 0,
    },
  });
}

Then call createFormActions function with the same form name as specified in useForm settings:

// Import type of form values from the file where you defined useForm
import { createFormActions } from '@mantine/form';
import type { DemoFormValues } from './DemoForm';

export const demoFormActions =
  createFormActions<DemoFormValues>('demo-form');

After that, you can use demoFormActions to change form state from anywhere in your application. For example, after a fetch request or after a user interaction with a component that does not have access to the form state:

import { useEffect } from 'react';
import { Button } from '@mantine/core';
import { demoFormActions } from './demoFormActions';

function ExternalComponent() {
  useEffect(() => {
    fetch('/api/user')
      .then((res) => res.json())
      .then((res) =>
        demoFormActions.setValues({
          name: res.name,
          age: res.age,
        })
      );
  }, []);

  return (
    <Button onClick={() => demoFormActions.reset()}>
      Reset demo form
    </Button>
  );
}

Form name

Form name must be a string that contains only letters, numbers and dashes:

import { useForm } from '@mantine/form';

// ✅ Valid form name
const valid = useForm({
  name: 'valid-FORM-name-10',
  mode: 'uncontrolled',
});

// ❌ Invalid form name: must not contain spaces and special characters
const invalid = useForm({
  name: 'invalid_form name',
  mode: 'uncontrolled',
});

Note that form names must be unique, if you have multiple forms with the same name, form actions will update the state of all forms with the same name.

Form actions

createFormActions function returns an object with the following methods:

setFieldValue
setValues
setInitialValues
setErrors
setFieldError
clearFieldError
clearErrors
reset
validate
validateField
reorderListItem
removeListItem
insertListItem
setDirty
setTouched
resetDirty
resetTouched

All methods work similar to use-form hooks methods – functions accept the same arguments but do not return anything.

Form context

Recipes