Not possible to assign value to useTemplateRef returned Ref

[ihardyslide]

Vue version

3.5.13

Link to minimal reproduction

https://stackblitz.com/edit/vitejs-vite-xibnqxg2?file=src%2Fcomponents%2FHelloWorld.vue

Steps to reproduce

I am currently in the process of refactoring my component library from using the old template ref approach, to using the useTemplateRef approach.
While doing this, I stumbled upon the following issue.
With the old approach, it was possible to set the reference to another value, in the new one it is not possible anymore, because the .value is readonly.

Please check the attached Stackblitz for further information.

• Open reproduction link
• Open console via Browser Dev-Tools
• Check console.log output

vue.js?v=546ca277:307 [Vue warn] Set operation on key "value" failed: target is readonly. 
RefImpl {dep: Dep, __v_isRef: true, __v_isShallow: true, _rawValue: div#2, _value: div#2}

As you can see, setting the ref to a new value was possible before, as the console logs no error/warning and the new value is logged correctly.
But setting the ref to a new value coming from useTemplateRef does not work.

What is expected?

possible to set returned reference value from useTemplateRef to a new value

What is actually happening?

not possible to set returned reference value from useTemplateRef to a new value

System Info

System:
    OS: Linux 5.10 Debian GNU/Linux 11 (bullseye) 11 (bullseye)
    CPU: (3) x64 11th Gen Intel(R) Core(TM) i7-1165G7 @ 2.80GHz
    Memory: 7.75 GB / 17.24 GB
    Container: Yes
    Shell: 5.1.4 - /bin/bash
  Binaries:
    Node: 22.14.0 - ~/.nvm/versions/node/v22.14.0/bin/node
    Yarn: 1.22.22 - ~/.nvm/versions/node/v22.14.0/bin/yarn
    npm: 11.1.0 - ~/.nvm/versions/node/v22.14.0/bin/npm
  Browsers:
    Chrome: 137.0.7151.68
  npmPackages:
    vue: ^3.5.13 => 3.5.16

Any additional comments?

Since nowhere in the docs it's stated that this is intentional behavior, I assume it is a bug.

[LinusBorg]

That behavior is intended, though admittedly could be made a bit more obvious in the docs.

Why is this intended? Because this ref is, as stated in the docs, "synced with the template element or component with a matching ref attribute."

In order to be synced at all times, we cannot allow the value to be changed to something else. At the next re-render, the sync process would inevitably reset it to point to the template element again, anyway.

If you need such behaviour, use a separate normal ref.

[ihardyslide]

Thanks for explaining!