Weird troubleshooting info for controlled inputs?

Hi team! 👋

During our translation work I came across a weird bit of troubleshooting advice on the <textarea> page.

Quite expectedly, it's also found in the <input> page.

It basically states that setting the controlling state variable to anything other than the raw e.target.value (e.g. transforming it to uppercase, used to illustrate the "bug", only it works just fine) is the cause for the caret jumping back to the beginning.

This seems misleading and borderline incorrect; one of the key benefits of controlled inputs is our ability to format / filter / validate values live (think phone numbers, SSNs, CC numbers, VAT identifiers, etc.) and this only moves the caret back when the resulting value is shorter. It doesn't reset it to the beginning.

Here's a CodeSandbox demonstrating things are just fine for many use-cases of setting the controlled value to a transformed version of the incoming DOM value.

Any light on this? What are the actually problematic patterns for caret jumping?

Best,

Start with the linked troubleshooting sections on the React DOM input and textarea reference pages, then reproduce the behavior in the provided CodeSandbox. Compare transformed controlled values with the documented caret-jumping scenario. Done means the documentation accurately explains which value-update patterns cause caret movement and no longer presents valid formatting use cases as misleading examples.