Vuejs.org: Document .native modifier on "Event Handling" page

[thejcannon]

The "Event Handling" page has a handy list of modifiers, which excludes .native as a valid modifier.
You don't learn about the .native modifier until you get all the way down to "Custom Events" (which is a somewhat misleading place to have to go to learn about it).

The .native modifier should be documented on the "Event Handling" page alongside it's brothers/sisters.

[NataliaTepluhina]

Thank you for reporting this issue! It was previously discussed within the docs team and we decided to leave it as-is for now.

The reason is: having .native modifier in Components In-Depth section makes sense. If you try to use .native not on custom Vue component but on native HTML element like button, you will notice the event handler is broken. Here is a quick example to check this behavior. So if we describe .native in the Event Handling section, people will probably use it _before_ they reach Components In-Depth and it might be used on native elements (which leads to the issue described above).

If we need a reference to _all possible event modifiers_ tho, we have native described in API Reference

[thejcannon]

I agree, having people use .native modifier without understanding the caveat(s) is a concern.

Take one person's opinion with a grain of salt, but the way I parse the __Components In-Depth__ section which introduces .native doesn't really describe it to the client, but rather to the component author (it briefly introduces it, describes a caveat, and then spends the majority of the real-estate on how to remedy the caveat as a component author). After-all, that whole section (__Components In-Depth__) speaks to component authors.
Whereas the __Event Handling__ section is documenting modifiers for the client to use.

My suggestion for clarity and focus would be:
On the __Event Handling__ page:

• Document the modifier from a client's perspective along with a warning (using a tip, which grabs the eye) about avoiding using it on custom components unless necessary

On the __Components In-Depth__ page:

• Document the dangers of refactoring your root component from something with native events to something without (because of .native) and how to avoid the potential breakage.

[NataliaTepluhina]

Thank you for your input!

First of all, we definitely should notify people about unwanted use of .native so I've submitted a PR to add a console warning when .native is used incorrectly: https://github.com/vuejs/vue/pull/9884

I will think about adding a warning about not using .native incorrectly to docs as well.

[sdras]

We also might want to hold off on much more work on this as the .native modifier might be removed soon (see RFC detail)

[sdras]

Here is also one suggestion I made to a PR about this (feel free to use if it seems relevant but I defer to @NataliaTepluhina on the matter) https://github.com/vuejs/vuejs.org/pull/1745#issuecomment-480666429

[NataliaTepluhina]

@thejcannon as https://github.com/vuejs/vue/pull/9884 got merged, user will get a console warning now when trying to use a native modifier on native HTML element. I decided not to add a similar warning to the docs but this decision is not written in stone: if we'll have reported issues about this case even after we introduced a console warning, maybe it will make sense to edit documentation.

Thank you for reporting this issue and for the discussion! I really appreciate your arguments and they led to the slight change in the Vue core :tada:
Closing this for now, feel free to reopen if you disagree :wink: