[@types/react] <Form onSubmit> should allow an async event handler

[jasikpark]

React allows passing an async event handler for onSubmit, for example, react-hook-form constructs handleSubmit, which returns a promise.

[@types/react] should allow for an async function to be passed, so that a rule like https://typescript-eslint.io/rules/no-misused-promises/ is not triggered, warning about dangling promises.

While () => void can accept () => Promise<void> as a subtype, it is useful to explicitly mention that an event handler may be asynchronous

TLDR: [@types/react] should allow async event handlers

[typescript-bot]

Thanks for the discussion about "react", some useful links for everyone:

• npm
• DT
• Related discussions

Pinging the DT module owners: @johnnyreilly, @bbenezech, @pzavolinsky, @ericanderson, @DovydasNavickas, @theruther4d, @guilhermehubner, @ferdaber, @jrakotoharisoa, @pascaloliv, @Hotell, @franklixuefei, @Jessidhia, @saranshkataria, @lukyth, @eps1lon, @zieka, @dancerphil, @dimitropoulos, @disjukr, @vhfmag, @hellatan, @priyanshurav, @Semigradsky.

[karlhorky]

@eps1lon what are your thoughts here on changing the React types to also accept async functions for event handlers?

Here's an example of an error from the recommended configuration of @typescript-eslint/no-misused-promises:

typescript-eslint Playground

index.tsx

import 'react';

export default function Component() {
  return <button onClick={async () => 0} />;
}

Error message:

Promise-returning function provided to attribute where a void return was expected. eslint (@typescript-eslint/no-misused-promises)

Workaround

Disable the lint warnings/errors about promise misuse reported using checksVoidReturn.attributes = false:

eslint.config.ts

'@typescript-eslint/no-misused-promises': [
  'error',
  {
    checksVoidReturn: {
      // Allow async functions passed to event handler props
      // - https://github.com/typescript-eslint/typescript-eslint/pull/4623
      // - https://github.com/typescript-eslint/typescript-eslint/issues/4619
      //
      // Although technically, async functions should not
      // be passed to event handler props:
      // - https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/66505#discussioncomment-10411110
      attributes: false,
    },
  },
],

[eps1lon]

We're discussing this internally. One thing to note is that calling any imperative method on event after the await would be a noop hinting at async event handlers being a footgun. For example, event.stopPropagation or event.preventDefault would not work after await.

The same applies to using .then but generally, that always has been the escape hatch when you pass an async function to something that treats the function as sync.

We're leaning towards allowing it but no final decision yet. If somebody could start filing a PR with the necessary changes to check ecosystem interop, that'd be helpful.

[karlhorky]

Oh nice, thanks for the follow-up!

I'm assuming that the PR has to do with changing the : void here on line 2344 of types/react/index.d.ts to : void | Promise<void>

DefinitelyTyped/types/react/index.d.ts

Lines 2340 to 2344 in 414f1e1

	//
	// Event Handler Types
	// ----------------------------------------------------------------------
	type EventHandler<E extends SyntheticEvent<any>> = { bivarianceHack(event: E): void }["bivarianceHack"];

Seems like maybe a good-first-issue or beginner PR (at least for this first part)

[ProchaLu]

@karlhorky @eps1lon Created a small PR #70086

[eps1lon]

We've discussed this and we don't want to allow async functions at the type level. We're probably going to start warning at runtime when you return a Promise from an event handler.

We didn't used to warn because we didn't have a good alternative. With React 19 we have: Use an Action or wrap the async function in startTransition.

We may start automatically wrapping async functions in startTransition. But with any additive API this comes with the risk of breaking existing usages that relied on existing behavior even though it was never supported. So by officially allowing them now (even though it "just works"), we increase the risk of not being able to make that change because too much of the ecosystem relied on this behavior.

As an escape hatch, you can always wrap the async function in an IIFE or use promise.then(). This makes it more obvious that something after the Promise resolved is outside of React's control.

[karlhorky]

Interesting, thanks for the feedback!

So then it sounds like it's a pretty official React team recommendation to avoid passing async functions to event handler props 👀

I guess that lots of blog posts, videos and other learning resources should consider adapting to this change in the mid-term.

Even libraries which promote this pattern (albeit in a component instead of an HTML element event handler prop directly) - such as React Hook Form (cc @bluebill1049) may want to consider what this means for them.

[jasikpark]

It really would be wonderful if TypeScript could model async functions as being separate from () => void at the type level, rather than requiring lints and whatnot. Unhandled promises are pretty easy to make use of since they fit inside the supertype of () => void v.s. () => Promise<void>

[markerikson]

Frankly that feels like it's going to end up adding another layer of boilerplate for a set of fairly common usage patterns.

Take this example:

const onClick = async () => {
  await dispatch(someReduxAsyncThunk()).unwrap();
  navigate("/");
}

You're saying React would start warning on that? It's annoying enough to have to wrap async calls in IIFEs inside of useEffect as it is.

I understand the idea that "if you access event after an await it will break", but I'm not sure that is enough of a footgun to justify forbidding async event handlers. Like, if that is the concern, maybe instrument event objects in dev to warn about accessing those fields instead?

[vcarl]

I do note that the patterns currently suggest in You Might Not Need An Effect to my eye look very much like recommending async behaviors be done in event handlers; this code (in practice) would require an await in the majority of cases I've experienced:

function handleSubmit(e) {
  e.preventDefault();
  // ✅ Good: Event-specific logic is in the event handler
  post('/api/register', { firstName, lastName });
}

Disallowing promise return types doesn't prevent someone from using promises within the handler, which would still run the same risks of stale values e.g.

function handleSubmit(e) {
  post('/api/register', { firstName, lastName })
    .then((response) => { /* … */ });
}