Controlled vs Uncontrolled

All Mantine inputs support both controlled and uncontrolled modes. This guide explains the difference between these two modes and when to use each of them.

Controlled components

A controlled component is a form element whose value is stored in React state. The value is passed with the value prop and updated in the onChange handler.

Example of a controlled TextInput component:

import { useState } from 'react';
import { TextInput } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState('');

  return (
    <TextInput
      label="Controlled TextInput"
      value={value}
      onChange={(event) => setValue(event.currentTarget.value)}
    />
  );
}

Every keystroke triggers a state update, which causes a re-render with the new value.

An uncontrolled component manages its own state through the DOM or internal state, similar to regular HTML form elements. Use refs or DOM methods to read the current value when needed, usually on form submission.

Example of an uncontrolled TextInput component:

import { useRef } from 'react';
import { TextInput, Button } from '@mantine/core';

function Demo() {
  const inputRef = useRef<HTMLInputElement>(null);

  const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();

    if (inputRef.current) {
      alert(`Input value: ${inputRef.current.value}`);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <TextInput label="Uncontrolled TextInput" ref={inputRef} />
      <Button type="submit">Submit</Button>
    </form>
  );
}

Key differences

Controlled components store state in React, uncontrolled components store it in the DOM
Controlled components use value prop, uncontrolled components use defaultValue
Controlled components require onChange handler to remain interactive, uncontrolled components work without change handlers, like regular HTML inputs

When to use which

Use controlled components when:

You need to validate or manipulate input values in real-time.
You want to enforce specific formats or constraints on user input.
You require immediate feedback or dynamic UI updates based on input changes.

Use uncontrolled components when:

You want to simplify your code and reduce boilerplate for simple forms.
You don't need to validate or manipulate input values until form submission.
You are working with large forms where performance is a concern, and you want to minimize re-renders.

FormData and uncontrolled components

Uncontrolled forms are often used with the FormData API, which allows you to easily collect form values without managing state for each input. All Mantine components support uncontrolled usage with FormData.

Example of using uncontrolled Checkbox with FormData:

import { Checkbox } from '@mantine/core';

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        console.log('Checkbox value:', !!formData.get('terms'));
      }}
    >
      <Checkbox label="Accept terms and conditions" name="terms" defaultChecked />
      <button type="submit">Submit</button>
    </form>
  );
}

Uncontrolled use-form

@mantine/form supports uncontrolled mode. Use it to build large forms with many fields without re-rendering the form on every change.

Example of uncontrolled mode with useForm:

import { useState } from 'react';
import { Button, Code, Text, TextInput } from '@mantine/core';
import { hasLength, isEmail, useForm } from '@mantine/form';

function Demo() {
  const form = useForm({
    mode: 'uncontrolled',
    initialValues: { name: '', email: '' },
    validate: {
      name: hasLength({ min: 3 }, 'Must be at least 3 characters'),
      email: isEmail('Invalid email'),
    },
  });

  const [submittedValues, setSubmittedValues] = useState<typeof form.values | null>(null);

  return (
    <form onSubmit={form.onSubmit(setSubmittedValues)}>
      <TextInput
        {...form.getInputProps('name')}
        key={form.key('name')}
        label="Name"
        placeholder="Name"
      />
      <TextInput
        {...form.getInputProps('email')}
        key={form.key('email')}
        mt="md"
        label="Email"
        placeholder="Email"
      />
      <Button type="submit" mt="md">
        Submit
      </Button>

      <Text mt="md">Form values:</Text>
      <Code block>{JSON.stringify(form.values, null, 2)}</Code>

      <Text mt="md">Submitted values:</Text>
      <Code block>{submittedValues ? JSON.stringify(submittedValues, null, 2) : '–'}</Code>
    </form>
  );
}

Custom components