use-form.mdx

group	package	title	order	slug	description	import	docs	source	license
mantine-form	@mantine/form	use-form	0	/form/use-form/	Manage form state	import { useForm } from '@mantine/form';	form/use-form.mdx	mantine-form/src	MIT

import { FormDemos } from '@mantine/demos';

Installation

@mantine/form package does not depend on any other libraries, you can use it with or without @mantine/core inputs:

Install with npm:

npm install @mantine/form

Install with yarn:

yarn add @mantine/form

Usage

API overview

useForm hook accepts a single argument with a configuration object that includes the following properties (all of them are optional):

• initialValues – initial form values, form types are generated based on this value
• initialErrors – initial form errors, object of React nodes
• initialTouched – initial touched state
• initialDirty – initial dirty state
• validate – an object with validation rules, schema or a validation function that receives form values as an argument and returns object with validation errors
• clearInputErrorOnChange – boolean value that determines whether input error should be clear when its value changes, true by default

Hook returns an object with the following properties:

• values – current form values
• setValues – handler to set all form values
• setFieldValue – handler to set value of the specified form field
• errors – current validation errors
• setErrors – sets validation errors
• clearErrors – clears all validation errors
• clearFieldError – clears validation error of the specified field
• setFieldError – sets validation error of the specified field
• removeListItem – removes list item at given field and index
• insertListItem – inserts list item at given index
• reorderListItem – reorders list item with given position at specified field
• validate – validates all fields, returns validation results
• validateField – validates specified field, returns validation results
• onSubmit – wrapper function for form onSubmit event handler
• onReset – wrapper function for form onReset event handler
• reset – resets values to initial state, clears all validation errors
• isTouched – returns boolean value that indicates that user focused or modified field
• isDirty – returns boolean value that indicates that field value is not the same as specified in initialValues
• setDirty – sets fields dirty state
• setTouched – sets fields touched state
• resetDirtyState – clears dirty state
• resetTouchedState – clears touched state
• getInputProps – returns an object with value, onChange and error that should be spread on input

UseFormReturnType

UseFormReturnType can be used when you want to pass form as a prop to another component:

import { TextInput } from '@mantine/core';
import { useForm, UseFormReturnType } from '@mantine/form';

interface FormValues {
  name: string;
  occupation: string;
}

function NameInput({ form }: { form: UseFormReturnType<FormValues> }) {
  return <TextInput {...form.getInputProps('name')} />;
}

function OccupationInput({ form }: { form: UseFormReturnType<FormValues> }) {
  return <TextInput {...form.getInputProps('occupation')} />;
}

function Demo() {
  const form = useForm<FormValues>({ initialValues: { name: '', occupation: '' } });
  return (
    <>
      <NameInput form={form} />
      <OccupationInput form={form} />
    </>
  );
}

Documentation

• Form values
• Form errors
• Touched & dirty status
• Form validation
• Nested fields
• Recipes