Importance of using keys in React

October 23, 2020

One of the most common patterns used in building React applications, is creating a list of React elements or components, say, a list of blog posts, by iterating over the dataset using Array.prototype.map. It is a very powerful pattern that lets us build lists and reuse components with ease. But, there is one thing which often gets overlooked. I am talking about the special prop provided by React called key.

For the sake of avoiding repetition I will be using the word "element(s)" to represent both React element(s) and React component(s) from this point forward.

When I first started working with React, almost always I missed setting the key prop on the list elements and actively ignored the warning caused by it. Because anything which throws a warning instead of an error isn’t worth paying much attention to, right?

Wrong!

I learned it the hard way that keys are a very important part of not only how React renders lists, but also how it optimizes performance across re-renders. There are two main reasons why you should always set the key prop on your list elements:

Improving Performance
Avoiding bugs caused by inconsistent UI state

Improving Performance

Lets look at an example to understand how setting keys can improve the performance of our app and vice versa.

Suppose, we have a list of notes.

// List 1
<Note note={note}>Note 1</Note>
<Note note={note}>Note 2</Note>
<Note note={note}>Note 3</Note>
<Note note={note}>Note 4</Note>

// List 2
<Note note={note}>Note 1</Note>
<Note note={note}>Note 2</Note>
<Note note={note}>Note 3</Note>
<Note note={note}>Note 4</Note>
<Note note={note}>Note 5</Note>

List 1 is before and List 2 after an element is added to the list. When an element is added to the list and a new tree is generated for the re-render, React just iterates over both lists (old tree vs new tree) and creates a mutation wherever it finds a change. In the code above when the element is added to the end of the list, there is no change when React compares the first 4 elements. Now, when it encounters the last element on List 2 it just inserts it into the DOM.

That was straightforward isn’t it. Hold on, what if the new element was added to the top instead of bottom?

// List 1
<Note note={note}>Note 1</Note>
<Note note={note}>Note 2</Note>
<Note note={note}>Note 3</Note>
<Note note={note}>Note 4</Note>

// List 2
<Note note={note}>Note 5</Note>
<Note note={note}>Note 1</Note>
<Note note={note}>Note 2</Note>
<Note note={note}>Note 3</Note>
<Note note={note}>Note 4</Note>

While comparing the old tree vs the new tree of elements, React finds a change for the first element and updates it. The same thing happens for the remaining Notes as well. And at the end of the list React creates a new element for Note 4 which was already in the previous list. As you might’ve noticed, this is a very naive approach to updating the DOM and will result in bad performance. A better approach to this would be to keep all the Notes from List 1 intact and just add Note 5 to the top.

To improve this inefficiency we can set the key prop on each Note element which gives React something to compare the old list elements, to the new list elements and only update the ones that have been changed or didn’t exist in the old tree.

// List 1
<Note key="_note85XB4" note={note} />
<Note key="_noteY7F32" note={note} />
<Note key="_noteUK3IR" note={note} />
<Note key="_note1O0QT" note={note} />

// List 2
<Note key="_noteB31XA" note={note} />
<Note key="_note85XB4" note={note} />
<Note key="_noteY7F32" note={note} />
<Note key="_noteUK3IR" note={note} />
<Note key="_note1O0QT" note={note} />

Now, if the key prop is provided for the elements, when the new element with key _noteB31XA is added to the top of the list, after the comparison, React knows it is the new element and all other elements already exist in the old tree. So, it keeps the old elements intact and just adds the new element to the top of the list. Its the same for any kind of mutation to the list; add, update or delete.

This is one of the main heuristics of React's Reconciliation algorithm which makes it so performant, and if this heuristic isn't met, performance of re-renders will suffer. To get a more detailed view of the Reconciliation (Diffing) algorithm checkout the references at the end of this post.

Avoiding bugs caused by inconsistent UI state

Suppose, we have an array of objects, in which each object represents the data for our Note element. Each object has some properties like id, title, description etc. We want to render this array of objects as a list of notes in the UI.

[
	{ id: "_note85XB4", title: "Da 5 Bloods", poster: "https://upload.wikimedia.org/wikipedia/en/thumb/f/f0/Da_5_Bloods_poster.jpeg/220px-Da_5_Bloods_poster.jpeg", description: "During the Vietnam War, a squad of Black US Army soldiers of the 1st Infantry Division, Paul, Otis, Eddie, Melvin and their squad leader Norman, who dub themselves the \"Bloods,\" secure the site of a CIA airplane crash and recover its cargo, a locker of gold bars intended as payment for the Lahu people for their help in fighting the Viet Cong. The Bloods decide to take the gold for themselves and bury it so they can retrieve it later. However, in the ensuing Vietnamese counter-attack, Norman is killed and the Bloods cannot locate the buried gold after a napalm strike obliterates all of the identifying landmarks. In the present day, Paul, Otis, Eddie and Melvin meet up in Ho Chi Minh City. A recent landslide had uncovered the tail of the crashed plane, and with this new information they plan to find the gold and Norman's body. Otis reunites with his old Vietnamese girlfriend Tiên, who reveals that he is the father of her grown child. Tiên introduces the Bloods to Desroche, a French businessman who agrees to help the Bloods smuggle the gold out of Vietnam once they retrieve it. Soon thereafter, Paul's son David joins the mission. Vinh, a tour guide hired by the Bloods, leads the group out into the countryside, where a confrontation with a local merchant forces Paul to admit that he has post-traumatic stress disorder. At a hotel bar, David meets Hedy, the founder of LAMB, an organization dedicated to clearing landmines. The next day, Vinh drops off the group and tells them he will pick them up in a few days. During their first night, Paul confiscates a pistol Otis had been secretly given by Tiên and becomes suspicious of his motives. Eventually, the Bloods find the gold bars scattered across the side of a hill. They also find Norman's remains and pray over them. Eddie reveals that his excessive spending has rendered him broke, but reminds the Bloods of Norman's original plan to give the gold to their black brethren in the United States." },
	{ id: "_noteY7F32", title: "The Way Back", poster: "https://upload.wikimedia.org/wikipedia/en/thumb/c/c3/The_Way_Back_poster.jpeg/220px-The_Way_Back_poster.jpeg", description: "Jack Cunningham is an alcoholic construction worker who is separated from his wife, Angela. While at Thanksgiving dinner with his mother, his sister Beth, and her family, Beth reveals that friends, including Angela, have expressed concern about his drinking and isolation from friends and family. The next day, Jack receives a call from Father Devine at his Catholic high school Bishop Hayes, where he was a star basketball player and led the team to multiple championships. Father Devine asks him to step in as the school's basketball coach, as the current coach has suffered a heart attack. Jack is initially reluctant, but accepts the job. Jack is introduced to assistant coach and algebra teacher Dan, as well as members of the team. Bishop Hayes has only won one game, and has not gone to the playoffs since Jack was a student. As a result, student interest in basketball has dropped greatly, leaving the team with just six varsity players. Among these players are Brandon, the team's introverted point guard and most talented player, and Marcus, the team's center, who aggravates his teammates and Jack with his attitude. Angela meets with Jack and reveals that she is seeing someone new. Jack continues drinking heavily; his friend Doc takes him home from the bar every night, making sure he arrives safely. The team faces Memorial, a larger school with a much more talented team, in one of Jack's first games as coach. Trailing significantly and frustrated at a perceived lack of effort, Jack benches Marcus and demands the team play with more toughness. Nevertheless, Bishop Hayes loses badly. Dan begins to notice signs of Jack's alcoholism, including an allusion to his drinking habits by Memorial's coach and finding beer cans in Jack's office." },
	{ id: "_noteUK3IR", title: "The Trial of the Chicago 7", poster: "https://upload.wikimedia.org/wikipedia/en/thumb/c/c2/TrialChicago7poster.jpeg/220px-TrialChicago7poster.jpeg", description: "In August 1968, Abbie Hoffman, Jerry Rubin, Tom Hayden, Rennie Davis, David Dellinger, Lee Weiner, John Froines, and Bobby Seale begin to prepare to protest at the Democratic National Convention in Chicago. Five months later, all eight of them are arrested and are charged with trying to incite a riot. John N. Mitchell, the Attorney General appoints Tom Foran and Richard Schultz as the prosecutors, while all the defendants except Seale are represented by William Kunstler and Leonard Weinglass. Judge Julius Hoffman shows significant prejudice for the prosecution. Seale's attorney is not present and he receives help from Fred Hampton. Abbie Hoffman openly antagonizes the court. Judge Hoffman begins removing jurors who are suspected of sympathizing with the defendants because of reported threats from the Black Panther Party and gives the defendants and their attorneys multiple contempt of court charges. Numerous undercover cops testify. One night, Hayden noticed two cops tailing Davis and attempted to let the air out of their tire, but was caught and later arrested. Abbie led a protest to the police station where Hayden was being kept, but turned around upon seeing the police blockade outside. When attempting to return to the park, police had taken control of the hill. A riot ensued, and the protestors claimed the hill again. Kunstler makes a point that none of the defendants instigated the riot. It is reported that Hampton is killed during a police raid. In retaliation to Seale continuing to speak up for his constitutional rights, Judge Hoffman has him taken to another room, beaten, and returned gagged and chained. Judge Hoffman takes Schultz's suggestion of declaring Seale's case a mistrial." },
	{ id: "_note1O0QT", title: "I'm Thinking of Ending Things", poster: "https://upload.wikimedia.org/wikipedia/en/2/2f/I%27m_Thinking_Of_Ending_Things_poster.jpeg", description: "A young woman contemplates ending her six-week relationship with her boyfriend, Jake, while taking a trip to meet Jake's parents on their farm. During the drive, Jake attempts to recite a poem he read when he was younger, Ode: Intimations of Immortality, and pressures the woman into performing one of her works in the car to pass time. After she recites a morbid poem about coming home, they arrive at the farmhouse. Jake takes the young woman to the barn, where he recounts a story about a maggot-infested pig. Throughout the drive, as well as later scenes in the film, the main narrative is intercut with footage of a janitor working at a high school, including scenes where he sees a musical production rehearsal, and a dance in the school's hallway. Inside the home, the young woman notices scratches on the basement door. At dinner with Jake's parents, the woman, who is described as having different occupations, shares one of her verses[a] and tells the story of how she and Jake met at a trivia night, told with narrative inconsistencies. Later, she notices a picture of Jake as a child, but becomes confused after recognizing that child as herself." },
	{ id: "_noteB31XA", title: "Enola Holmes", poster: "https://upload.wikimedia.org/wikipedia/en/e/e6/Enola_Holmes_poster.jpeg", description: "Enola Holmes is the youngest sibling in the famous Holmes family. She is extremely intelligent, observant, and insightful, and defies the social norms for women of the time. Her mother, Eudoria, has taught her everything from chess to jujitsu and encouraged her to be a strong-willed and independent thinking young woman. On the day of her sixteenth birthday, Enola awakens to find that her mother has disappeared, leaving behind only some birthday gifts. She rushes to the train station to meet her brothers, Mycroft and Sherlock, who fail to recognize her at first, not having seen her in many years. Sherlock finds her to be an intelligent girl, whereas Mycroft finds her troublesome. As her legal guardian, Mycroft intends to send her away to a finishing school run by the stern Miss Harrison. The flowers left by her mother reveal secret messages and lead to hidden money, which Enola uses to escape disguised as a boy. On the train, she finds the young Viscount Tewkesbury hidden in a travel bag. She thinks he is a nincompoop but warns him that a man in a brown bowler hat (named Linthorn) is on the train searching for him. They jump off the train to escape. Neither having any food, Tewkesbury forages for edible plants. They travel to London, where they part ways." },
];

Here is how we create a list from this data

const Note = ({ note }) => {
	const [showFullDescription, enableFullDescription] = useState(false);

	const { title, poster, description } = note;

	const toggleNoteDescription = () => {
		if (!showFullDescription) {
			enableFullDescription(true);
		}
	};

	return (
		<div className="note-wrapper">
			<div className="note-cover">
				<img alt={title} src={poster} />
			</div>
			<section className="note-content">
				<header>
					<h3 className="note-title heading">{title}</h3>
				</header>
				<div className="note-description" onClick={toggleNoteDescription}>
					<p>{description}</p>
				</div>
			</section>
		</div>
	);
};

const NotesList = ({ data }) => {
	data.map((note, index) => {
		return <Note key={note.id} note={note} />;
	});
};

Lets see how the list looks after actually rendering. I am using a slightly simpler version of the Note component that I use on the Notes page of this website. The description of each note can be expanded by clicking on the description text. I handle this via showFullDescription variable kept in the local state of the Note element.

Da 5 Bloods

During the Vietnam War, a squad of Black US Army soldiers of the 1st Infantry Division, Paul, Otis, Eddie, Melvin and their squad leader Norman, who dub themselves the "Bloods," secure the site of a CIA airplane crash and recover its cargo, a locker of gold bars intended as payment for the Lahu people for their help in fighting the Viet Cong. The Bloods decide to take the gold for themselves and bury it so they can retrieve it later. However, in the ensuing Vietnamese counter-attack, Norman is killed and the Bloods cannot locate the buried gold after a napalm strike obliterates all of the identifying landmarks. In the present day, Paul, Otis, Eddie and Melvin meet up in Ho Chi Minh City. A recent landslide had uncovered the tail of the crashed plane, and with this new information they plan to find the gold and Norman's body. Otis reunites with his old Vietnamese girlfriend Tiên, who reveals that he is the father of her grown child. Tiên introduces the Bloods to Desroche, a French businessman who agrees to help the Bloods smuggle the gold out of Vietnam once they retrieve it. Soon thereafter, Paul's son David joins the mission. Vinh, a tour guide hired by the Bloods, leads the group out into the countryside, where a confrontation with a local merchant forces Paul to admit that he has post-traumatic stress disorder. At a hotel bar, David meets Hedy, the founder of LAMB, an organization dedicated to clearing landmines. The next day, Vinh drops off the group and tells them he will pick them up in a few days. During their first night, Paul confiscates a pistol Otis had been secretly given by Tiên and becomes suspicious of his motives. Eventually, the Bloods find the gold bars scattered across the side of a hill. They also find Norman's remains and pray over them. Eddie reveals that his excessive spending has rendered him broke, but reminds the Bloods of Norman's original plan to give the gold to their black brethren in the United States.

The Way Back

Jack Cunningham is an alcoholic construction worker who is separated from his wife, Angela. While at Thanksgiving dinner with his mother, his sister Beth, and her family, Beth reveals that friends, including Angela, have expressed concern about his drinking and isolation from friends and family. The next day, Jack receives a call from Father Devine at his Catholic high school Bishop Hayes, where he was a star basketball player and led the team to multiple championships. Father Devine asks him to step in as the school's basketball coach, as the current coach has suffered a heart attack. Jack is initially reluctant, but accepts the job. Jack is introduced to assistant coach and algebra teacher Dan, as well as members of the team. Bishop Hayes has only won one game, and has not gone to the playoffs since Jack was a student. As a result, student interest in basketball has dropped greatly, leaving the team with just six varsity players. Among these players are Brandon, the team's introverted point guard and most talented player, and Marcus, the team's center, who aggravates his teammates and Jack with his attitude. Angela meets with Jack and reveals that she is seeing someone new. Jack continues drinking heavily; his friend Doc takes him home from the bar every night, making sure he arrives safely. The team faces Memorial, a larger school with a much more talented team, in one of Jack's first games as coach. Trailing significantly and frustrated at a perceived lack of effort, Jack benches Marcus and demands the team play with more toughness. Nevertheless, Bishop Hayes loses badly. Dan begins to notice signs of Jack's alcoholism, including an allusion to his drinking habits by Memorial's coach and finding beer cans in Jack's office.

The Trial of the Chicago 7

In August 1968, Abbie Hoffman, Jerry Rubin, Tom Hayden, Rennie Davis, David Dellinger, Lee Weiner, John Froines, and Bobby Seale begin to prepare to protest at the Democratic National Convention in Chicago. Five months later, all eight of them are arrested and are charged with trying to incite a riot. John N. Mitchell, the Attorney General appoints Tom Foran and Richard Schultz as the prosecutors, while all the defendants except Seale are represented by William Kunstler and Leonard Weinglass. Judge Julius Hoffman shows significant prejudice for the prosecution. Seale's attorney is not present and he receives help from Fred Hampton. Abbie Hoffman openly antagonizes the court. Judge Hoffman begins removing jurors who are suspected of sympathizing with the defendants because of reported threats from the Black Panther Party and gives the defendants and their attorneys multiple contempt of court charges. Numerous undercover cops testify. One night, Hayden noticed two cops tailing Davis and attempted to let the air out of their tire, but was caught and later arrested. Abbie led a protest to the police station where Hayden was being kept, but turned around upon seeing the police blockade outside. When attempting to return to the park, police had taken control of the hill. A riot ensued, and the protestors claimed the hill again. Kunstler makes a point that none of the defendants instigated the riot. It is reported that Hampton is killed during a police raid. In retaliation to Seale continuing to speak up for his constitutional rights, Judge Hoffman has him taken to another room, beaten, and returned gagged and chained. Judge Hoffman takes Schultz's suggestion of declaring Seale's case a mistrial.

I'm Thinking of Ending Things

A young woman contemplates ending her six-week relationship with her boyfriend, Jake, while taking a trip to meet Jake's parents on their farm. During the drive, Jake attempts to recite a poem he read when he was younger, Ode: Intimations of Immortality, and pressures the woman into performing one of her works in the car to pass time. After she recites a morbid poem about coming home, they arrive at the farmhouse. Jake takes the young woman to the barn, where he recounts a story about a maggot-infested pig. Throughout the drive, as well as later scenes in the film, the main narrative is intercut with footage of a janitor working at a high school, including scenes where he sees a musical production rehearsal, and a dance in the school's hallway. Inside the home, the young woman notices scratches on the basement door. At dinner with Jake's parents, the woman, who is described as having different occupations, shares one of her verses[a] and tells the story of how she and Jake met at a trivia night, told with narrative inconsistencies. Later, she notices a picture of Jake as a child, but becomes confused after recognizing that child as herself.

Enola Holmes

Enola Holmes is the youngest sibling in the famous Holmes family. She is extremely intelligent, observant, and insightful, and defies the social norms for women of the time. Her mother, Eudoria, has taught her everything from chess to jujitsu and encouraged her to be a strong-willed and independent thinking young woman. On the day of her sixteenth birthday, Enola awakens to find that her mother has disappeared, leaving behind only some birthday gifts. She rushes to the train station to meet her brothers, Mycroft and Sherlock, who fail to recognize her at first, not having seen her in many years. Sherlock finds her to be an intelligent girl, whereas Mycroft finds her troublesome. As her legal guardian, Mycroft intends to send her away to a finishing school run by the stern Miss Harrison. The flowers left by her mother reveal secret messages and lead to hidden money, which Enola uses to escape disguised as a boy. On the train, she finds the young Viscount Tewkesbury hidden in a travel bag. She thinks he is a nincompoop but warns him that a man in a brown bowler hat (named Linthorn) is on the train searching for him. They jump off the train to escape. Neither having any food, Tewkesbury forages for edible plants. They travel to London, where they part ways.

The list above is rendered with the key prop set to the index of the element. Go ahead and click on the description of the first note in the list. It should expand to show a bigger description. Now, try sorting the list using the dropdown on the top right of the list. You will observe that although the first element has changed, its description is expanded, which we never did. Go ahead and check the description of the note that you expanded before sorting. You will see that its description isn’t expanded anymore. What is happening here?

Well, as we learnt in the previous section React uses the key prop to compare elements before a re-render occurs. In this case we set the key prop to the index of the element. Now when the sorting occurs, in the updated tree the key of the first element is same as it was before sorting which is 0. So, in-order to make the re-render performant React just updates the props of the element (which is the note data) and preserves the state of the element. The value of showFullDescription of the element with key prop set to 0 is true therefore it displays the expanded description of the note. Using index as key isn’t a good idea as it not only causes inconsistent UI state behaviour but also slows down re-ordering the elements.

This is a big problem, which can easily be fixed by setting unique and stable a key prop for each element of the list. The list rendered below uses stable keys. Lets repeat what we did for the above list and see if the problem still persists or not.

Da 5 Bloods

The Way Back

The Trial of the Chicago 7

I'm Thinking of Ending Things

Enola Holmes

Voila! the problem is solved.

You can probably get away by using index as the key prop when there are no re-orders involved, like sorting and filtering. But, I think you should set it anyway to avoid problems in the future.

What value to set in the key prop?

Most datasets usually have a unique and stable identifier (usually id) associated with each element you are trying to render. If not, you can create a hash by combining other properties from the dataset.

Some things to keep in mind while using keys

Keys must only be unique amongst siblings and not throughout the scope of your React app.
Keys don't get passed to the components like other props.

Hopefully, this post might’ve convinced you to start using keys next time you are creating a list in React.

References:

React docs on Reconciliation