Merge branch 'fl-document-key-vue' into 'master'

Adds guidelines regarding `:key` keyword

See merge request gitlab-org/gitlab-ce!17400

1 files changed, 51 insertions, 0 deletions

diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md
index 917d28b48ee..7b5fa6ca42f 100644
--- a/doc/development/fe_guide/style_guide_js.md
+++ b/doc/development/fe_guide/style_guide_js.md
@@ -548,6 +548,57 @@ On those a default key should not be provided.
 1. Properties in a Vue Component:
   Check [order of properties in components rule][vue-order].
 
+#### `:key`
+When using `v-for` you need to provide a *unique* `:key` attribute for each item.
+
+1. If the elements of the array being iterated have an unique `id` it is advised to use it:
+    ```html
+      <div
+        v-for="item in items"
+        :key="item.id"
+      >
+        <!-- content -->
+      </div>
+    ```
+
+1. When the elements being iterated don't have a unique id, you can use the array index as the `:key` attribute
+    ```html
+      <div
+        v-for="(item, index) in items"
+        :key="index"
+      >
+        <!-- content -->
+      </div>
+    ```
+
+
+1. When using `v-for` with `template` and there is more than one child element, the `:key` values must be unique. It's advised to use `kebab-case` namespaces.
+    ```html
+      <template v-for="(item, index) in items">
+        <span :key="`span-${index}`"></span>
+        <button :key="`button-${index}`"></button>
+      </template>
+    ```
+
+1. When dealing with nested `v-for` use the same guidelines as above.
+      ```html
+        <div
+          v-for="item in items"
+          :key="item.id"
+        >
+          <span
+            v-for="element in array"
+            :key="element.id"
+          >
+            <!-- content -->
+          </span>
+        </div>
+      ```
+
+
+Useful links:
+1. [`key`](https://vuejs.org/v2/guide/list.html#key)
+1. [Vue Style Guide: Keyed v-for](https://vuejs.org/v2/style-guide/#Keyed-v-for-essential )
 #### Vue and Bootstrap
 
 1. Tooltips: Do not rely on `has-tooltip` class name for Vue components