Form actions

Change form state from anywhere in the application

Docs

Package

Usage

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

To use form actions, set the 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 the 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 names must be strings that contain 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 that name.

Form actions

The 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 similarly to use-form hook methods – the functions accept the same arguments but do not return anything.

Form context

Recipes