GitHub link for the code below: https://github.com/prakash118/react-key-prop
When rendering lists in React, the key prop is essential. It's a special attribute that you assign to each item in the list, providing a unique identifier. This allows React to efficiently update the DOM when items are added, removed, or reordered. Let's see how it's used in practice.
Contents
The in-depth explanation is below the Scenarios section. You can skip the scenarios by clicking "Solution - Reconciliation" if you'd like, but they are referenced in the explanation.
Scenarios
#1 - Dynamic components (map list)
Let's examine the common use case of rendering a list of components using Array.map() with an uncontrolled form fields without key prop.
...
const [user, setUser] = useState(
userDetail.map((name) => ({ name, value: '' }))
);
...
{user.map(({ name }) => (
<div>
<label>{name}</label>
<input name={name} onChange={handleChange} placeholder={name} />
<button onClick={()=> handleDelete(name)}>Delete</button>
</div>
))}
...React will issue a warning: "Each child in a list should have a unique 'key' prop.", so let's address this by adding the necessary key prop.
...
{user.map(({ name }, index) => (
<div key={index}>
...
</div>
))}
...While using the array index as the key prop silences the warning, it doesn't actually solve the underlying problem—in fact, it can make things worse. This approach merely masks the issue, and even adding a prefix (e.g., key={`user-detail-${index}`}) doesn't change the fundamental problem: the key is still derived from the index.
The screenshot shows the user data on the left and the corresponding form fields on the right. While the form might appear correct initially, but deleting a field reveals unexpected behavior. Let's try deleting the email field to see what happens.
The image clearly shows that although the email field is no longer in the DOM, its value has incorrectly shifted to the phone field. This result doesn't match the user data displayed on the left.
We'll investigate the reasons for this behavior shortly. For now, let's use the key prop correctly to resolve the issue.
...
{user.map(({ name }) => (
<div key={name}> // firstname || lastname
...
</div>
))}
...#2 - Conditionally rendered component
Let's consider another scenario: a simple conditional rendering of an input field. This form allows users to specify their preferred salutation, choosing to be addressed by either their first or last name.
...
const [hide, setHide] = useState(true);
...
{hide ? (
<input name="first_name" id="first_name" onChange={handleChange} />
) : (
<input name="last_name" id="last_name" onChange={handleChange} />
)}
...The image below shows the resulting state after a first name is entered and the checkbox is subsequently unchecked.
This scenario presents a similar problem to the Scenario #1. While the initial rendering appears correct, entering text and then unchecking the checkbox leaves the entered value in the input field, contrary to the expectation that the field should clear. Code inspection reveals that the component re-renders with the name and ID attributes set to "last_name".
As expected, the key prop has fixed this issue too; unchecking the checkbox now clears the input field. But how does the key prop work, and why is it so crucial for resolving these kinds of problems?
Reconciliation
In React, reconciliation is the process React uses to efficiently update the DOM when there are changes to your application's data. It's the mechanism that allows React to be performant by minimizing the number of actual DOM manipulations, which are often slow.
The diagram illustrates React's reconciliation process. React maintains a lightweight JavaScript object representation of the DOM, known as the Virtual DOM. When a component's props or state change, React re-renders, creating a new Virtual DOM tree. It then compares this new tree to the previous one using a process called "diffing" or "reconciliation". This comparison identifies the minimal changes needed to update the actual DOM—additions, removals, or updates to elements. Finally, React applies these changes to the real DOM.
Scenario #2 breakdown
Knowing that the Virtual DOM is represented as JavaScript objects, let's analyze Scenario #2 and examine how React interprets our code.
...
<input
id="prefered"
name="prefered_name"
type="checkbox"
defaultChecked={hide}
onChange={()=> setHide(!hide)}
/>
{hide ? (
<>
<label htmlFor="first_name">First name</label>
<input name="first_name" id="first_name" onChange={handleChange} />
</>
) : (
<>
<label htmlFor="last_name">Last name</label>
<input name="last_name" id="last_name" onChange={handleChange} />
</>
)}
...The image below illustrates the object representation of this code, showing the component tree both before and after the checkbox is unchecked.
Note: The following Virtual DOM object representations are simplified for illustrative purposes only and do not reflect the actual internal structure of React's Virtual DOM.
The Virtual DOM stores not just the component tree, but also the component's state. This is why the input value isn't cleared when the component is removed. During reconciliation, React compares the previous and current Virtual DOM objects item by item. In this scenario, the component type remains the same, so the component is re-rendered, but its state is preserved. The resulting Virtual DOM object effectively mimics a conditional assignment to the name and id props, as shown below.
...
const fieldName = hide ? "first_name" : "last_name";
...
<input name={fieldName} id={fieldName} onChange={handleChange} />
...Now that we understand how the Virtual DOM functions, let's modify the code to correctly interact with the component by adding null to the component tree.
{hide ? (
<>
<label htmlFor="first_name">First name</label>
<input
name="first_name"
id="first_name"
onChange={handleChange}
/>
</>
) : null}
{!hide ? (
<>
<label htmlFor="last_name">Last name</label>
<input
name="last_name"
id="last_name"
onChange={handleChange}
/>
</>
) : null}This code resembles the original, but with two conditional checks instead of one. How does this translate to the component tree in Virtual DOM?
As the image shows, React now compares the object with null after the checkbox is unchecked. This unmounts the first_name field, destroying its state, and then mounts the last_name field. This resolves our issue, although we'll ultimately use the key prop solution instead.
So why is the key prop the best solution? During reconciliation, React's diffing algorithm prioritizes the key property when comparing components. If a key is present, React uses it to identify specific items. The key prop ensures that each component is uniquely identifiable. When comparing the old and new Virtual DOMs, if React encounters a component of the same type but with a different key, it understands that this is a new component. The old component is unmounted and its state destroyed, and the new component is mounted.
Scenario #1 breakdown
This explains the problem in Scenario #2 and the importance of the key prop. Now, let's take a closer look at Scenario #1.
The "Before" section depicts the initial rendering of the dynamic components and their associated states. However, deleting the "lastname" field removes the field visually but preserves its state. This preserved state is then incorrectly applied to the subsequent field in the Virtual DOM, creating a mismatch with our intended state (as shown in the Scenario #1 image).
Bonus
We can resolve this by using the key prop, ensuring the uniqueness of each component within the dynamic list. The GIF below demonstrates the modified component, shuffling the form fields on every change while correctly updating and preserving the state at the sametime.
GitHub link for the code https://github.com/prakash118/react-key-prop/blob/main/src/components/user-detail.tsx
Conclusion
In summary, while the key prop is crucial for preventing certain issues, misusing it can create new problems. Incorrectly used keys can lead to performance bottlenecks from excessive re-renders of large components, updates to the wrong components and their states, and instability if keys are not unique.