React Input Components: Controlled & Uncontrolled Guide (2026)

Building versatile input components in React that can function as both controlled and uncontrolled is a common requirement in modern applications. This tutorial will guide you through creating a custom input component that can seamlessly operate in either mode, similar to popular libraries like Material-UI or Chakra UI.

Key Takeaways

• Understand the difference between controlled and uncontrolled components in React.
• Learn how to build a flexible input component that supports both modes.
• Implement the component with practical examples and best practices.
• Explore common pitfalls and how to troubleshoot them effectively.

React's flexibility allows developers to create components that can adapt to different use cases. This capability is particularly useful when building forms where components need to handle both controlled and uncontrolled behavior. By the end of this tutorial, you will have a robust understanding of how to implement such a component, providing you with the tools to enhance your React projects.

Prerequisites

• Basic knowledge of React and JavaScript.
• Understanding of state and props in React.
• Node.js and npm installed on your machine.
• Create React App or a similar setup for running React applications.

Step 1: Understanding Controlled vs Uncontrolled Components

In React, a controlled component is an input form element whose value is controlled by React state. The input's value is set by the state, and any changes to the input are managed via state updates. This provides a consistent and predictable way to manage form inputs.

// Controlled Component Example
const ControlledInput = () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event) => {
    setValue(event.target.value);
  };

  return (
    
  );
};

An uncontrolled component, on the other hand, relies on the DOM to handle its state. This approach can be simpler for certain use cases and allows for the use of refs to access the input value directly.

// Uncontrolled Component Example
const UncontrolledInput = () => {
  const inputRef = React.useRef(null);

  const handleSubmit = () => {
    alert('Input Value: ' + inputRef.current.value);
  };

  return (
    
      
      Submit
    
  );
};

Step 2: Setting Up the Base Component

We will start by creating a simple input component that can handle both controlled and uncontrolled scenarios. The component will accept a value prop, and if it is provided, the component will act as controlled. Otherwise, it will default to uncontrolled behavior using a ref.

import React, { useState, useRef } from 'react';

const CustomInput = ({ value, onChange, ...props }) => {
  const [internalValue, setInternalValue] = useState('');
  const inputRef = useRef(null);

  const isControlled = value !== undefined;

  const handleChange = (event) => {
    if (isControlled) {
      onChange(event);
    } else {
      setInternalValue(event.target.value);
    }
  };

  return (
    
  );
};

Step 3: Using the Component in Controlled Mode

To use the CustomInput component in controlled mode, simply pass the value and onChange props.

const ControlledUsage = () => {
  const [text, setText] = useState('');

  return (
     setText(e.target.value)}
      placeholder="Controlled Input"
    />
  );
};

Step 4: Using the Component in Uncontrolled Mode

When you omit the value prop, the component will default to uncontrolled behavior, managing its own state internally.

const UncontrolledUsage = () => (
  
);

Step 5: Handling Both Behaviors

The flexibility of the CustomInput component allows it to be used in either mode based on the presence of the value prop. This dual functionality is useful in larger applications where some forms require controlled inputs for validation, while others can be simpler.

Common Errors/Troubleshooting

Here are some common issues you might encounter when creating a dual-mode input component, along with solutions:

• State Desynchronization: Ensure that the value prop is correctly managed when switching between controlled and uncontrolled modes.
• Ref Handling: If using refs in uncontrolled mode, ensure they are initialized and accessed properly to avoid null errors.
• Prop Types: Consider using prop-types to enforce that either value or defaultValue is used, but not both.

Conclusion

Creating input components that can function as both controlled and uncontrolled provides flexibility and adaptability in React applications. This tutorial demonstrated how to build such a component, offering a balanced approach between simplicity and control. By understanding and implementing these principles, you can enhance your React toolkit and create more dynamic and versatile user interfaces.

Frequently Asked Questions

What is a controlled component in React?

A controlled component is one where the form data is handled by the React component's state, making the component the single source of truth.

How does an uncontrolled component work?

An uncontrolled component uses the DOM as the source of truth, allowing you to access input values using refs.

Can a component be both controlled and uncontrolled?

Yes, a component can be designed to operate in both modes, allowing flexibility based on the presence of certain props.

Frequently Asked Questions

What is a controlled component in React?

A controlled component is one where the form data is handled by the React component's state, making the component the single source of truth.

How does an uncontrolled component work?

An uncontrolled component uses the DOM as the source of truth, allowing you to access input values using refs.

Can a component be both controlled and uncontrolled?

Yes, a component can be designed to operate in both modes, allowing flexibility based on the presence of certain props.