use-form

Manage form state
Import

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

import { TextInput, Checkbox, Button, Group, Box } from '@mantine/core';
import { useForm } from '@mantine/form';
function Demo() {
const form = useForm({
initialValues: {
email: '',
termsOfService: false,
},
validate: {
email: (value) => (/^\S+@\S+$/.test(value) ? null : 'Invalid email'),
},
});
return (
<Box sx={{ maxWidth: 300 }} mx="auto">
<form onSubmit={form.onSubmit((values) => console.log(values))}>
<TextInput
required
label="Email"
placeholder="your@email.com"
{...form.getInputProps('email')}
/>
<Checkbox
mt="md"
label="I agree to sell my privacy"
{...form.getInputProps('termsOfService', { type: 'checkbox' })}
/>
<Group position="right" mt="md">
<Button type="submit">Submit</Button>
</Group>
</form>
</Box>
);
}

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

Documentation