name attribute on radio buttons with v-model: yes or no?

[arun-mani-j]

Hii.

To save your time: When making custom components with radio buttons and v-model, should we include name? If not, can this be documented in https://vuejs.org/guide/essentials/forms.html#radio-1?

I made a custom component that has a set of radio buttons with v-model, and displayed the chosen value. Something like this:

<script setup>
import { ref } from 'vue'

const picked = ref('One')
</script>

<template>
  <div>Picked: {{ picked }}</div>

	<input type="radio" id="one" name="x" value="One" v-model="picked" />
	<label for="one">One</label>

	<input type="radio" id="two" name="x" value="Two" v-model="picked" />
  <label for="two">Two</label>
</template>

However I found that whenever I clicked a radio button, the displayed picked value changed, but the actual radio button did not get selected. If I click again, then it got selected.

I tried all possible things to reproduce the error, including making a new project, removing CSS, making a duplicate of the component with only non-trivial stuff, but everything failed. I could produce the problem only in one page of my app and that too when I placed it in inside <header>.

Frustrated, I asked LLM and it told me:

The most common cause of this behavior in Vue 3 (with native elements and v-model or defineModel()) is including a name attribute on the radio inputs.
Vue manages radio groups internally via the shared v-model binding: it sets the checked property on the matching input and unchecks others. However, if you add a name attribute (even a dynamic one like :name="someGroup"), the browser's native radio grouping takes over. This can conflict with Vue's management, especially when the component is reused or the DOM updates in certain ways — leading to the model updating correctly (ref changes), but the visual "checked" state lagging or requiring a second click to sync.

(Not trying to praise LLM, but giving credit where due).

So I tried removing name attribute and it worked fine now! If I added back the name attribute, the problem was back.

The LLM refused to share links, but when I searched online for "Vue radio-button name v-model", I found this blog - https://williamhuster.com/radio-buttons-in-vue/. OP also faced the same problem and resolved it by removing name attribute.

This is still a mystery to me and searching for "name" in https://vuejs.org/guide/essentials/forms.html#radio-1 does not show any information about whether we should include name attribute in radio buttons.

So I'm wondering if this is a well known problem and if this can be documented in Vue's docs.

Thank you.