Clarify onChange differences between React and HTML #9014
Conversation
First time reading about react, and I thought the docs were wrong when they said that onChange is fired on every keystroke, since the HTML change event is only fired when focus changes. Looks like the docs are right, but I think they ought to be clarified. I've attempted the clarification here, but a cross reference to something more authoritative about React's changes to HTML events would be good, too.
| @@ -66,7 +66,7 @@ class NameForm extends React.Component { | |||
|
|
|||
| [Try it on CodePen.](https://codepen.io/gaearon/pen/VmmPgp?editors=0010) | |||
|
|
|||
| Since the `value` attribute is set on our form element, the displayed value will always be `this.state.value`, making the React state the source of truth. Since `handleChange` runs on every keystroke to update the React state, the displayed value will update as the user types. | |||
| Since the `value` attribute is set on our form element, the displayed value will always be `this.state.value`, making the React state the source of truth. Since `handleChange` runs on every keystroke to update the React state, the displayed value will update as the user types. (Note that this is a React enhancement to standard HTML. The `onChange` event handler of a React `<input>` element is triggered on every keystroke. But for the underlying HTML DOM `<input>` element displayed by the browser, a change event is only fired when the user enters text and then changes the focus by typing Return or Tab or by clicking the mouse.) | |||
There was a problem hiding this comment.
Maybe we can just make "runs on every keystoke" a link, and point it to https://facebook.github.io/react/docs/dom-elements.html#onchange?
There was a problem hiding this comment.
"on every value change" if you want to be truthful, it's not just about keystrokes ;)
There was a problem hiding this comment.
"on every value change" might be misleading, since onChange is not called if the value is updated programmatically.
There was a problem hiding this comment.
@aweary True, it's tough to be precise for that one. Could add "by user" or something, but perhaps "every keystroke" is good enough, I assume most will correctly interpret the intent (or simply not consciously think about there being other ways to mutate the value and not question it).
There was a problem hiding this comment.
Maybe rephrase as "whenever the value is updated in the input" or something. It's more verbose but might be clearer
There was a problem hiding this comment.
I just want to emphasize that the issue I filed the PR about is not uncertaintly about the precise details of when onChange is triggered, but the huge intentional difference between React's onChange and the DOM's onchange.
I'm a reader who knows the DOM well but has never used React. This is my first time reading the docs. And when I reached this point, I was confused and assumed the docs were wrong.
My proposed fix is incomplete because it doesn't link to any further explanation. But really, if this was something I was writing, I'd actually add a whole new section near the top of this document summarizing the ways that React rationalizes the legacy DOM to make onChange and value work consistently for form elements. If you had a paragraph or two on that up at the top of this document on forms, that would solve the problem nicely.
Let me know if you're interested in a PR to add those paragraphs.
As for the "on every keystroke" issue, how about "whenever the user changes the text displayed in the text field" or something to that effect. That excludes programmatic changes, but includes pastes done with a mouse.
|
Thank you for filing this PR! I'm sorry to be the bearer of bad news, but the documentation and source code for reactjs.org now lives in a different repository: reactjs/reactjs.org. (For more info on why we made this move, see issue #11075.) Would you be willing to re-open this PR on the new repo? I promise we'll review it quickly! |
First time reading about react, and I thought the docs were wrong when they said that onChange is fired on every keystroke, since the HTML change event is only fired when focus changes. Looks like the docs are right, but I think they ought to be clarified. I've attempted the clarification here, but a cross reference to something more authoritative about React's changes to HTML events would be good, too.