docs: clarify .once listener attachment semantics#3425
Open
happysnaker wants to merge 1 commit into
Open
Conversation
✅ Deploy Preview for vuejs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
bencodezen
reviewed
Jul 3, 2026
| - `.self` - only trigger handler if event was dispatched from this element. | ||
| - `.{keyAlias}` - only trigger handler on certain keys. | ||
| - `.once` - trigger handler at most once. | ||
| - `.once` - trigger handler at most once for each listener attachment. |
Member
There was a problem hiding this comment.
"listener attachment" is not very clear to me. What about:
Suggested change
| - `.once` - trigger handler at most once for each listener attachment. | |
| - `.once` - trigger handler at most once for each event listener. |
bencodezen
reviewed
Jul 3, 2026
|
|
||
| `v-on` also supports binding to an object of event / listener pairs without an argument. Note when using the object syntax, it does not support any modifiers. | ||
|
|
||
| The `.once` modifier removes the listener after its first invocation. If the element or child component is re-created later, a new listener is attached, so it can run once again. |
Member
There was a problem hiding this comment.
This description is slightly inaccurate given .once has different behavior for native DOM elements vs components.
Rather than a dedicated paragraph here though, maybe it makes more sense for it to be described more in depth in the list?
See https://github.com/vuejs/docs/pull/3425/changes#r3521256033
bencodezen
reviewed
Jul 3, 2026
| - `.self` - only trigger handler if event was dispatched from this element. | ||
| - `.{keyAlias}` - only trigger handler on certain keys. | ||
| - `.once` - trigger handler at most once. | ||
| - `.once` - trigger handler at most once for each listener attachment. |
Member
There was a problem hiding this comment.
Suggested change
| - `.once` - trigger handler at most once for each listener attachment. | |
| - `.once` - trigger handler at most once for each event listener. The event is removed in native DOM events and ignored (rather than removed) in a component emitted event instance. |
bencodezen
requested changes
Jul 3, 2026
bencodezen
left a comment
bencodezen
left a comment
Member
There was a problem hiding this comment.
Thanks for the PR @happysnaker! I left some comments on the PR. Let me know what you think or if you have any questions!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.onceapplies once per listener attachmentCloses #3033
Note
This PR supersedes #3423, which I had to close after the original fork relationship was broken during repo visibility changes on my side. The content is being resubmitted unchanged from a proper public fork.