Native event listener types should allow a promise return type

Open Beginner friendly
#16,337 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@willnie9 is already working on this.

Since Nov 18, 2026.

  • #16339 by @willnie9 — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
75/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript

Research direction

Start with EventHandlers in packages/runtime-dom/src/jsx.ts and the minimal reproduction linked in the issue. Check how the listener type interacts with async handlers and @typescript-eslint/no-misused-promises, then run the reproduction’s lint command. Done when an async native listener no longer triggers the lint error and Vue’s promise rejection handling remains available.

Written by the indexing model from the issue text.

Description

scope: types
Vue version

3.5.45 (main at 0f4002c has the same types)

Link to minimal reproduction

https://github.com/magurotuna/vue-async-native-listener-no-misused-promises-repro

Steps to reproduce
  1. npm install
  2. npx eslint .
What is expected?

No lint error from no-misused-promises for <button onClick={load}>, where load is an async function.
Vue catches a promise that a native listener returns and sends a rejection to app.config.errorHandler (events.ts, errorHandling.ts, and the docs).

What is actually happening?

@typescript-eslint/no-misused-promises reports

/Users/yt/tmp/vue-async-native-listener-no-misused-promises-repro/src/App.tsx
  13:32  error  Promise-returning function provided to attribute where a void return was expected  @typescript-eslint/no-misused-promises

✖ 1 problem (1 error, 0 warnings)

because EventHandlers types the listener as (payload: MouseEvent) => void. tsc gives no error. Tools that type-check templates give the same report for <button @click="load">.

System Info
System:
    OS: macOS 26.7.1
    CPU: (12) arm64 Apple M3 Pro
    Memory: 121.02 MB / 36.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 24.21.0 - /Users/yt/.nix-profile/bin/node
    npm: 11.19.0 - /Users/yt/.nix-profile/bin/npm
    pnpm: 12.9.0 - /Users/yt/.nix-profile/bin/pnpm
    bun: 1.4.2 - /Users/yt/.nix-profile/bin/bun
    Deno: 2.9.7 - /Users/yt/.nix-profile/bin/deno
    Watchman: 2026.07.27.00 - /Users/yt/.nix-profile/bin/watchman
  Browsers:
    Chrome: 157.0.8103.79
    Firefox: 159.0
    Safari: 26.6.2
  npmPackages:
    vue: 3.5.45 => 3.5.45
Any additional comments?

The usual fix for this report is onClick={() => void load()}, but then a rejection is unhandled and does not reach app.config.errorHandler, which is worse.

typescript-eslint accepts a union with a promise-returning member typescript-eslint/typescript-eslint#4841, so the following change would be an option to solve this issue:

type EventHandlers<E> = {
  [K in keyof E]?: E[K] extends (...args: any) => any
    ? E[K]
    : ((payload: E[K]) => void) | ((payload: E[K]) => Promise<unknown>)
}

This type well declares the fact that the handler's return value is actually used by Vue to catch errors, if it is a promise.

I tried this change on 43 open-source Vue projects, and it added no type errors.

Related: #14249 (the same lint error for watchEffect).

Dominant language
TypeScript
Stars
55k
Forks
9.3k
Avg merge
1d 9h
Merged PRs (30d)
194

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from vuejs/core

All issues in vuejs/core

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.