Migration guide section about v-if key

[AjaiKN]

Edit: It seems like the behavior has changed on the master branch since I posted this yesterday, so the following description is out of date. I think it's still a breaking change, so the migration guide might still need a section on this. However, it might be good to wait a little bit before working on that, since it seems possible that the behavior could change again before the next release.

---

I can't find anything about this in the migration guide, but it seems to be a breaking change.

Example A

Vue 2

In v2, it was common to use keys on v-if, v-else, and v-else-if. For example:

<h1 v-if="cond" key="a">A</h1>
<h2 v-else key="b">B</h2>

Vue 3

In v3, this produces an compiler error because keys are automatically generated on v-if, v-else, and v-else-if nodes. These keys can be removed:

<h1 v-if="cond">A</h1>
<h2 v-else>B</h2>

Example B

Vue 2

In v2, a <template> could not have a key, so when using a <template v-for="..."> with a child v-if/v-else, you would place the key on both of the children:

<template v-for="thing in list">
  <h1 v-if="cond" :key="thing.id">A</h1>
  <h2 v-else :key="thing.id">B</h2>
</template>

Vue 3

In v3, the previous example causes the v-if to not work properly, and it produces an error message. Because of Fragments, we can now put the key on the <template> directly:

<template v-for="thing in list" :key="thing.id">
  <h1 v-if="cond">A</h1>
  <h2 v-else>B</h2>
</template>

Error message

This is the new error message for this problem in the master branch of vue-next. (This new message isn't released into a new version yet.)

v-if branches must use compiler generated keys. In many cases, you can simply remove this key. If this tag is inside of a <template v-for="...">, then you can move the key up to the parent <template>.

References

• Console warning when using a v-if on an element inside a v-for on a template core#1734 (comment)
• $attrs not updating when change attrs via template v-if core#1712 (comment)

[NataliaTepluhina]

@Aurelius333 thank you for reporting this! I was writing Conditional rendering guide around this change indeed (so no keys there) but I haven't realized that v2 code with v-if + key would result in compiler error. Let's wait for the next release and then add this to migration guide

[AjaiKN]

In case it's helpful, here's my understanding of how it works as of the latest release.

As of v3.0.0-rc.6, it seems like it’s okay to provide explicit keys on v-if/v-else/v-else-if nodes, as long as the keys are always different in different branches. So "Example A" above is no longer a problem and doesn't need to be changed when upgrading to Vue 3.

It seems like there are two breaking changes involved here. These could be two different sections in the migration guide, or maybe they could be combined into one section about changes to key usage. My "Example B" in the issue description is a combination of both of these breaking changes.

Change 1: v-if/v-else/v-else-if branches must use unique keys if keys are provided (but these keys aren't necessary).

<div v-if="cond" :key="3">Yes</div>
<div v-else :key="3">No</div>

We can probably just recommend removing the keys in this case, since the compiler can now generate them for you.

Change 2: <template v-for> key should be placed on the <template> tag (rather than on its child).

Vue 2:

<template v-for="thing in list">
  <div :key="thing.id">...</div>
</template>

Vue 3:

<template v-for="thing in list" :key="thing.id">
  <div>...</div>
</template>

[NataliaTepluhina]

@Aurelius333 would you mind creating a pull request with these changes or would you prefer me to create it? 😅

[AjaiKN]

@NataliaTepluhina I'd be happy to create a pull request.