Events
A .vue template binds a listener the usual way, such as @click or @keydown. Every listener receives one event object with the fields and methods of the DOM Event interface (see Base fields).
<template>
<div @mousedown="onMouseDown">Click and hold</div>
</template>Event targets
- The mount container (the container
mount()targets, see Elements) stands in forhtmlandbodyincomposedPath(). - A removed node drops its listeners.
addEventListener()and an assignment to a handler property do nothing on it. - An attribute that holds code, such as
onclick="count++", runs nothing. documenthas nobody,headordocumentElement.windowhas the event members only, with nolocation,navigatororperformance, and the host fires noresizeorloadevent at it.documentandwindowneed no import.globalThis.windowandglobalThis.documentstay undefined, andwindow.window,selfandwindow.globalThisare absent. A dependency that teststypeof windowfinds a window.- A root that a hand-built renderer mounts cannot reload on a
<script>edit, becausewindow.locationis absent. - A window close and a quit run no
beforeunload,pagehideorunloadlistener.
Event modifiers
Templates accept the event modifiers and the key modifiers of Vue.
Base fields
Every event object carries the fields of the DOM Event interface. This includes the legacy aliases srcElement, cancelBubble and returnValue. The three flags depend on the event:
| Events | bubbles | cancelable | composed |
|---|---|---|---|
| mouse, wheel and keyboard events | yes | yes | yes |
mouseenter, mouseleave | no | no | no |
scroll | no | no | no |
focus, blur | no | no | yes |
focusin, focusout | yes | no | yes |
beforeinput, composition events | yes | yes | yes |
input | yes | no | yes |
change | yes | no | no |
- A
beforeinputofinsertCompositionTextis not cancelable. timeStampcounts milliseconds since the app was loaded, on the clock ofperformance.now().- The
viewof a UI event isnull. - Assigning
innerHTMLorouterHTMLfiresblurandfocusoutwhen the focused node leaves the tree. Every other removal or move of the focused node leaves them unfired.
Mouse
Mouse events carry the fields of MouseEvent from Pointer Events. wheel carries the fields of WheelEvent from Pointer Events.
click, auxclick and contextmenu carry the fields of PointerEvent.
| Event | button | buttons | detail |
|---|---|---|---|
click | 0 | 0 | click count |
dblclick | 0 | 0 | 2 |
auxclick | 1 to 4 | 0 | click count |
contextmenu | 2 | 2 | 0 |
Host differences
- On macOS a Ctrl+click fires
contextmenuwithbutton0 andbuttons1. preventDefault()in acontextmenulistener only setsdefaultPrevented.screenXandscreenYadd the window position. On Wayland they equal the client position.scrollendis unsupported.- A mouse event outside every element has the mount container as
target. Moving the pointer between an element and an empty area gives the mount container asrelatedTarget. - While the mount container is removed from
document, a key event with nothing focused hasdocumentastarget.
Pointer
Pointer events carry the fields of PointerEvent and follow Pointer Events. Pointer events come from the mouse only, with pointerId 1. pointercancel is never dispatched. The capture methods are in Elements.
Host differences
tiltX,tiltY,twist,tangentialPressure,altitudeAngle,azimuthAngle,persistentDeviceId,getCoalescedEvents()andgetPredictedEvents()ofPointerEventare unsupported.
Keyboard
Keyboard events carry the fields of KeyboardEvent from UI Events. With nothing focused, keydown, keypress and keyup go to the mount container.
| Field | Value |
|---|---|
key | "Unidentified" when the platform reports none |
repeat | false on keyup |
location | 0 |
codeis an empty string.keyidentifies the key.keyCodeandwhichofkeydownandkeyupgive the code ofkeyon a US keyboard layout, and 0 for a key outside it, such asé.- A key the input method takes during a composition fires no
keydown,keypressorkeyup. getModifierState()accepts Control, Shift, Alt, Meta and Accel. Accel is Meta on macOS and Control elsewhere.- Pressing a modifier alone fires
keydownandkeyupwith its name askey. - Shift+F10 fires
contextmenuon Linux and Windows only. - The quit shortcut (Cmd+Q on macOS, Ctrl+Q elsewhere) goes to the host only.
Input
beforeinput and input carry the fields of InputEvent from Input Events, and the composition events carry the fields of CompositionEvent from UI Events.
Host differences
copy,cutandpasteare never dispatched. The clipboard shortcuts of aninputread and write the clipboard directly.selectandselectionchangeare never dispatched.inputTypeis limited to the values for typing, a paste, a composition, Enter, Backspace, Delete and a cut.
Focus
Focus events carry the fields of FocusEvent from UI Events. Focus and Tab navigation follow the HTML tabindex rules, with the differences below.
Host differences
- A node takes focus through its
tabindexattribute. Without one, only abutton, aninput, anawithhrefand an SVGawithhreforxlink:hreftake focus, and.focus()on other nodes is ignored. hidden="until-found"counts as shown.- A focus ring is unsupported.
- After the last node, Tab leaves nothing focused and the next Tab starts at the first node. Focus stays in the window.
Dispatching events
dispatchEvent() sends an event that a script builds with an event constructor.
initUIEvent(),initMouseEvent(),initKeyboardEvent()andinitCompositionEvent()are unsupported methods.- The
viewmember of an init dictionary is ignored, andrelatedTargettakes any object. - The
modifierAltGraph,modifierCapsLockand the othermodifiermembers of an init dictionary are ignored. offsetXandoffsetYof a mouse event a script builds equalclientXandclientY, also while it is dispatched.- The
dataTransferandtargetRangesmembers of anInputEventInitare ignored.
Errors in handlers
An error a handler throws, or an async handler rejects with, follows Vue's error handling.
The development window reports an error that no hook takes to the terminal that ran inca dev, and shows it as an application error. A packaged app writes it to the log file of the run, see Run log. Install app.config.errorHandler to show these errors in the app.