To Be or Not to Be

Choosing between controlled and uncontrolled components in React

Controlled and uncontrolled components are two important concepts in React. It is vital to understand the difference between them and which cases best suit them.

What are controlled and uncontrolled components in React?

• A controlled component manages its children’s data.
• An uncontrolled component lets its children manage their own data.

The children mentioned in the above definition are typically HTML form elements, such as <input>, <textarea>, <select>, etc. In this article, we are going to use <input type=”text”> as example.

The children can also be React components.

Uncontrolled components use the natural HTML way, letting the DOM hold and update their values. The following App is an uncontrolled component, where the input value is maintained by the HTML element, <input>.

Controlled components are called the React way, recommended by the React team.

A controlled input accepts its value via a prop, and provides a callback to update this value. This value is typically held by the component’s state. The usage is straightforward.

Let’s use some examples to see the difference between controlled and uncontrolled components.

Example 1: Convert Each Input Keystroke to Uppercase

How do we manage an uncontrolled component? React provides event handlers to detect a change and then uses a callback to respond to the change.

In the below case, the onChange handler converts the uncontrolled input value to the uppercase. This happens on each keystroke.

This can be accomplished by using a controlled component as follows:

Example 2: Convert Each Input Keystroke to Uppercase With an Initial Value

We modify example one a bit to have an initial value. Here is how an uncontrolled component handles an initial value.

Here is how a controlled component handles an initial value:

Example 3: Convert Input to Uppercase After Clicking a Button

In this example, we want to demonstrate how the input element is managed by an outside event. The uppercase conversion is delayed until a button is clicked.

We face a problem. From the button’s event handler, we are not able to access this uncontrolled input field.

React provides refs to resolve this kind of problem. A ref is a way to access a DOM element or a React element.

In the following code, React.useRef() generates a ref, textInput. This ref is passed into the input element, and causes textInput.current to point to this input element when it is mounted.

Then, we are able to use textInput.current to manage this uncontrolled input value.

Here is the matching controlled component example:

Example 4: Convert Valid Input to Uppercase

We add validation to this example. Here, only letters are valid input. When an invalid key is typed, it is ignored and a red error message is displayed.

For an uncontrolled component, the generic onChange event handler is replaced by onKeyPress, since we may need to stop the default behavior before onChange happens.

For a controlled component, it doesn’t need to change the event handler, and neither does it need to prevent default behavior for the input element.

Example 5: Form Submission Use Case

Here is a form submission use case:

• There are two input fields: name and email. Name is a required field, and email needs to pass a regular expression test.
• The first error is displayed in red if there is a validation error.
• The submit button is enabled only when all input values are valid.
• Immediately after submitting the form, the sent info is shown. This message stays until a user starts entering new values.

The following code uses an uncontrolled component. The uncontrolled-specific lines are highlighted, where handleChange performs the validation and enables/disables the button.

const App = () => {
  const [error, setError] = React.useState('');
  const [submission, setSubmission] = React.useState('');
  const form = React.useRef();
  const handleChange = () => {
    const { name, email, submit } = form.current;
    if (!name.value) {
      setError('Name is required');
      submit.disabled = true;
    } else if (!/^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/.test(email.value)) {
      setError('Invalid email');
      submit.disabled = true;
    } else {
      setError('');
      submit.disabled = false;
    }
    setSubmission('');
  };
  const handleSubmit = e => {
    e.preventDefault();
    const { name, email, submit } = form.current;
    if (!error) {
      setSubmission(`Sent info - name: ${name.value}, email: ${email.value}`)
      submit.disabled = true;
      e.target.reset();
    }
  };
  return (
    <form ref={form} onSubmit={handleSubmit}>
      <input name="name" onChange={handleChange}/>
      <input name="email" onChange={handleChange}/>
      <div>{submission}</div>
      <button name="submit" disabled type="submit">Submit</button>
    </form>
  );
}

Here is the equivalent controlled component code. The controlled-specific lines are highlighted, where handleChange updates children’s data and React.useEffect performs the validation and enables/disables the button.

const App = () => {
  const [name, setName] = React.useState('');
  const [email, setEmail] = React.useState('');
  const [isDisabled, setIsDisabled] = React.useState(true);
  const [error, setError] = React.useState('');
  const [submission, setSubmission] = React.useState('');
  const handleChange = e => {
    if (e.target.name === 'name') {
      setName(e.target.value);
    } else if (e.target.name === 'email') {
      setEmail(e.target.value);
    }
    setSubmission('');
  };
  const handleSubmit = e => {
    e.preventDefault();
    if (!error) {
      setName('');
      setEmail('');
      setSubmission(`Sent info - name: ${name.value}, email: ${email.value}`)
      setIsDisabled(true);
    }
  };
  React.useEffect(() => {
    if (!submission) {
      if (!name) {
        setError('Name is required');
        setIsDisabled(true);
      } else if (!/^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/.test(email)) {
        setError('Invalid email');
        setIsDisabled(true);
      } else {
        setError('');
        setIsDisabled(false);
      }
    }
  }, [submission, name, email]);  
return (
    <form onSubmit={handleSubmit}>
      <input name="name" value={name} onChange={handleChange}/>
      <input name="email" value={email} onChange={handleChange}/>
      <div style={{color: "red"}}>{error}</div>
      <div>{submission}</div>
      <button name="submit" disabled={isDisabled} type="submit">Submit</button>
    </form>
  )
}

Example 6: Component With React Children

We have mentioned in the beginning that the method identifying controlled and uncontrolled components can be applied to React component’s children.

In the following example, App is an uncontrolled component, although its child,ShowUpperCase, is a controlled component.

The same behavior can be coded in the controlled way. The following App is a controlled component, that manages data for ShowUpperCase. ShowUpperCase is also a controlled component.

Conclusion

You have seen a few examples of controlled and uncontrolled components. Either way works. You can choose a way to code your use cases.

However, stick to one way for a specific component. Do not mix controlled and uncontrolled ways for the same component. Also, do not switch the type during the component’s lifetime.

Occasionally, you may encounter this warning in the debugger console:

A component is changing an uncontrolled input of type checkbox to be controlled. Input elements should not switch from uncontrolled to controlled (or vice versa).

This may be caused by you unexpectedly setting the state to null or undefined, which is considered uncontrolled in React. When you unset a value, remember to set it to ‘’ or false.

Now it’s time to test your knowledge!

In the following code, is App a controlled or uncontrolled component?

The answer is uncontrolled.

The App is written as a controlled component, but the undefined value switches the input element to be uncontrolled!

Thanks for reading. I hope this was helpful. If you have any questions, feel free to leave a response.