Welcome to Mantine, React components library that you always wished for
Welcome to Mantine, React components library that you always wished for

Form actions

Change form state from anywhere in the application

Docs

Edit this page

Package

@mantine/form

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.

Previous

Form context

Next

Recipes

Welcome to Mantine, React components library that you always wished for

Build fully functional accessible web applications faster than ever

About

ContributeAbout MantineChangelogReleases

Community

Chat on DiscordFollow on XFollow on GithubGitHub discussions

Project

Mantine UIDocumentationGithub organizationnpm organization

Built by Vitaly Rtishchev and these awesome people