stack/packages/mosaic/framework/skills/vue-best-practices/reference/render-function-v-for-keys-required.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Always Include key Props When Rendering Lists in Render Functions	HIGH	Missing keys cause inefficient re-renders and state bugs in dynamic lists	best-practice	vue3 render-function v-for performance key

Always Include key Props When Rendering Lists in Render Functions

Impact: HIGH - Omitting key props when rendering lists with h() or JSX causes Vue to use an inefficient "in-place patch" strategy, leading to performance issues and state bugs when list items have internal state or are reordered.

When rendering lists in render functions using .map(), always include a unique key prop on each item. This is the render function equivalent of using :key with v-for in templates.

Task Checklist

• Always provide a key prop when mapping over arrays in render functions
• Use unique, stable identifiers (like id) for keys, not array indices
• Ensure keys are primitive values (strings or numbers)
• Never use the same key for different items in the same list

Incorrect:

import { h } from 'vue';

export default {
  setup() {
    const items = ref([
      { id: 1, name: 'Apple' },
      { id: 2, name: 'Banana' },
    ]);

    return () =>
      h(
        'ul',
        // WRONG: No keys - causes inefficient patching
        items.value.map((item) => h('li', item.name)),
      );
  },
};

// WRONG: Using array index as key when list can be reordered
export default {
  setup() {
    const todos = ref([...])

    return () => (
      <ul>
        {todos.value.map((todo, index) => (
          <TodoItem
            key={index}  // Bad: index changes when list reorders
            todo={todo}
          />
        ))}
      </ul>
    )
  }
}

Correct:

import { h } from 'vue';

export default {
  setup() {
    const items = ref([
      { id: 1, name: 'Apple' },
      { id: 2, name: 'Banana' },
    ]);

    return () =>
      h(
        'ul',
        // CORRECT: Unique id as key
        items.value.map((item) => h('li', { key: item.id }, item.name)),
      );
  },
};

// CORRECT: Using stable unique identifier as key
export default {
  setup() {
    const todos = ref([
      { id: 'a1', text: 'Learn Vue' },
      { id: 'b2', text: 'Build app' },
    ]);

    return () => (
      <ul>
        {todos.value.map((todo) => (
          <TodoItem
            key={todo.id} // Good: stable unique identifier
            todo={todo}
          />
        ))}
      </ul>
    );
  },
};

import { h } from 'vue';

export default {
  setup() {
    const users = ref([]);

    return () =>
      h('div', [
        h('h2', 'User List'),
        h(
          'ul',
          users.value.map((user) =>
            h('li', { key: user.email }, [
              // email is unique
              h('span', user.name),
              h('span', ` (${user.email})`),
            ]),
          ),
        ),
      ]);
  },
};

When Index Keys Are Acceptable

Using array indices as keys is acceptable ONLY when:

1. The list is static and will never be reordered
2. Items will never be inserted or removed from the middle
3. Items have no internal component state

// Index is OK here: static list that never changes
const staticLabels = ['Name', 'Email', 'Phone'];

return () =>
  h(
    'tr',
    staticLabels.map((label, index) => h('th', { key: index }, label)),
  );

Why Keys Matter

Without keys, Vue uses an "in-place patch" strategy:

1. It reuses DOM elements in place
2. Updates element content to match new data
3. This breaks when components have internal state or transitions

With proper keys:

1. Vue tracks each item's identity
2. Elements are moved, created, or destroyed correctly
3. Component state is preserved during reorders

Reference

• Vue.js Render Functions - v-for