RFC: useEvent

[gaearon]

In this RFC, we propose a useEvent Hook. It lets you define event handlers that can read the latest props/state but have always stable function identity. Event handlers defined with useEvent don't break memoization and don't retrigger effects.

View formatted RFC

FAQ:

• What we're looking for in naming
• Why not add this behavior to useCallback?
• Why not allow calling it during render?
• Can the passed function be async?

---

Update (Sep 2022): we're planning to revise this proposal (and possibly rename it)

[windmaomao]

Finally something easy to think of is implemented as it seems. 👍🏻

[ds300]

Great idea ❤️

My main suggestion would be a different name. useEvent is not a very precise way to convey what this hook does. I've seen it implemented in other codebases as useStableCallback, which I slightly prefer, although I see that you've already dismissed it as being too verbose in the RFC.

[Merri]

Or maybe just name this useCallback and make it work for both cases, but deprecate the passing of dependencies and remove some version later.

Unless someone can figure out any valid use case for the old useCallback functionality with deps.

[windmaomao]

As for the name, IMHO, react hook is never named for tech purpose, more in the business direction. If i really want to be picky, i can think of useGlobal or useStatic.

[panta82]

I've been using this all over the place. I call it useLatestClosure. It's definitely the missing piece of React.

I don't like useEvent naming. IMO using these as events will be a very minor part of usage pattern, just an optimization in the largest codebases. Mostly it will be used when you need to pass a function somewhere where you don't want to trigger re-render.

Give the useEvent behavior to useCallback. We don’t want to do this because they have sufficiently different semantics.

I think this would be a better change. I almost always want to use useLatestClosure (or useEvent) and almost never useCallback with an argument list.

As Merri said, useCallback should just adopt this functionality when called without deps. And deps usage should be an advanced optimization use case.

[nikparo]

Great to see a proposal for this! I'm left wondering though what type of footguns you have identified related to using event functions during render? Out of date callbacks?

Same proposal, but allow calling event handlers during rendering. We think this creates too many footguns.

If calling event handlers during rendering was allowed, then would the event handler be up to date or not? I.e. would isCurrent in the example below always be true? If that is a possibility, then I think it warrants serious consideration.

  const [value, setValue] = useState(0);
  const getCurrentValue = useEvent(() => value);

  // always true or sometimes false?
  const isCurrent = value === getCurrentValue();

[kocyigityunus]

I didn't like the useEvent naming too. maybe split it into two different hooks.

1. useChange => with dependencies, since it re-runs when one of the dependencies changes.
2. useFunction or useFunctionRef => without dependencies. since it's basically useRef for a function.

[franciscop]

To be implementation-clear, the behaviour proposed here is not the same as this, right?

// NOT the proposal? Since it would have stale props
const useEvent = (cb) => {
  const wrapper = useCallback(cb, []);
  return wrapper;
};

Nevertheless, text inside useEvent will reflect its latest value

It'd be more like this (+some err handling), which means the wrapper is always stable but inside keeps the latest ref to the callback and calls that when invoked:

const useEvent = (cb) => {
  const ref = useRef(cb);
  useEffect(() => {
    ref.current = cb;
  }, [cb]);
  const wrapper = useCallback((...args) => {
    ref.current(...args);
  }, []);
  return wrapper;
};

[alvarlagerlof]

Please Keep the name. It's far less abstract than the other proposals, which will help a lot of non-native speakers.

[rubennorte]

@franciscop there's an example of the internal implementation of this hook in the proposal: https://github.com/reactjs/rfcs/blob/useevent/text/0000-useevent.md#internal-implementation

[franciscop]

What happens when the event is asynchronous?

This is a big usecase IMHO and a big pain point in current React's useEffect where you cannot do useEffect(async () => {...});. I see little mention of this very typical usecase (only "events should usually not be asynchronous"), what happens here? Is this valid?

const onClick = useEvent(async e => {
  ...
});

I think for a Hook that is going to be used in a highly-async environment, it'd be nice to have some async help in-place. Like, at the very least allow the callback to be async by design.

Disclaimer: I've written part of use-async-effect and all of use-async 😬

[rubennorte]

Sorry to continue with the bikeshedding on the name of the hook, but I think my perspective is slightly different from what has been shared already.

I think the concept of "event" aligns well with what these functions are intended for. Given they're not meant to be used during render (they can only be used when the tree has been committed) the only moment when they can actually execute is during an event (a user interaction event, a network event, a timer event, etc.).

My only concern is about calling it just useEvent because the name might suggest this is to subscribe to events, like:

useEvent('click', () => {
  // do something
});

Which isn't what it does.

In order to avoid this confusion, I think we should use something like useEventHandler or useEventCallback.

[so1ua]

useFunction is better :) Especially that as I understand useCallback will almost not be used later

[rubennorte]

What happens when the event is asynchronous?

This is a big usecase IMHO and a big pain point in current React's useEffect where you cannot do useEffect(async () => {...});. I see little mention of this very typical usecase (only "events should usually not be asynchronous"), what happens here? Is this valid?

const onClick = useEvent(async e => {
  ...
});

I think for a Hook that is going to be used in a highly-async environment, it'd be nice to have some async help in-place. Like, at the very least allow the callback to be async by design.

Disclaimer: I've written part of use-async-effect and all of use-async 😬

@franciscop what kind of help are you thinking about here? What do you think React should do differently when passing an async function instead of a sync one, considering React just returns a stable version of the function but doesn't really call that function itself?

[ScottAwesome]

First and foremost, this solves a huge pain point for the community. I love it so much. The over proliferation of useCallback and associated bugs are solved pretty concisely in this addition.

In terms of naming: I think you could call it useEventHandler. I see the purpose of useCallback being useful for things where you need data invalidation to change the function signature, like when interacting with results from an API. I does become more of an edge case tool but that's kind of the point? Arguably, one could just use useMemo for complex cases too, but the simplicity of useCallback for non event handling cases is nice.

Perhaps clarify guidance around async functions, e.g. if you are using an async action it might be better to treat it as a Promise rather than using async and await?

[franciscop]

I'm thinking to at least allow the function to be async, since if it's async in useEffect even when the return value is not used officially it'll give you a strong warning an error. Like, as far as it doesn't get in the way of that I'd be happy already.

What I was thinking as active help is that if this function (which doesn't seem to be the case from the RFC, but the name is slightly confusing) was supposed to be to manage only events like onClick it could also help by calling event.persist() by default. Though I'm just reading that it seems that event.persist() is useless since React 17 and I didn't know that, so there might be nothing else to do here!

Edit: I should re-read the docs more often, React keeps getting better in small ways (not needing e.persist()) and I didn't even notice.

[sompylasar]

I'd also argue strongly against useEvent name because an "event" is something that happens, but what we're making with this hook is a callback function which is supposed to handle/process the happened event. Suggest more specific useEventCallback or useEventHandler instead, even though it's longer to type. I would avoid going as abstract as useLatestClosure or useFunction.

[gaearon]

Hey folks, thanks to everyone for the discussion! We've implemented a prototype in facebook/react#25229 so you can play with it in the @experimental releases. However, we've also realized that we don't feel confident in coupling the two different motivations (rendering optimization and "fixing" Effects) under this single proposal.

In particular, we're worried that this proposal creates a strong incentive to wrap every function that currently uses useCallback into useEvent. However, that wouldn't lead to right semantics where the function identity is important. Since useEvent "erases" reactivity of the values flowing into it, we think there need to be additional limitations on where it makes sense to do the wrapping. In most cases, only the final consuming side (e.g. the Effect from which the event function is called) can be "sure" whether it "cares" about the reactivity of the function value. So using it widely seems premature.

For rendering optimizations, we are researching and developing an auto-memoizing compiler. It's not yet clear if the optimization described in this RFC would still be impactful when the compiler is on, so we will be revisiting this question as a part of that ongoing research. There are also other alternative ways to optimize this pattern that we might want to consider.

For now, we would like to shelve the current RFC, with a plan to publish a different, more scoped down RFC that supersedes this one. Since the new RFC will be different in scope, we might also give that Hook a different name.

---

tl;dr

• We're still committed to solving both problems in Motivation, but maybe not at the same time.
• We'll submit a more focused RFC to deal with the second motivation (preventing re-triggering of useEffect).
• We expect that updated RFC will be similar to this one but have slight differences in usage and possibly naming.

[landisdesign]

Thank you, @gaearon and Team, for putting this out and moderating the sometimes contentious debates. I appreciate the goal behind this RFC and look forward to its replacement.

[gaearon]

To clarify, the current plan is for the next RFC to have the same API, but with slightly different usage recommendations, slightly different semantics, and possibly a different name. I’ve seen some posts going around saying this RFC is “dead”, and that seems to give an impression that we’re abandoning this entire approach. In reality, we want to split this proposal and add a few extra constraints to it.

[mrcljx]

In particular, we're worried that this proposal creates a strong incentive to wrap every function that currently uses useCallback into useEvent. However, that wouldn't lead to right semantics where the function identity is important.

In case this datapoint is helpful for the other RFCs, we implemented a slightly modified version of the proposed useEffect to help with the semantics.

Implementation:

1. The implementation is the user-space implementation.
   1. Future: We'll probably switch to the experimental implementation.
2. Our signature requires that the callback's return type must be (async) void.

   function useEvent<T extends (...args: any[]) => void | Promise<void>>(callback: T): T;
   

   1. A useEventWithResult variant exists that allows non-void results. It was deliberately picked to be "longer" to write and comes with a big "be sure that this isn't a case for useCallback" warning.
   2. Alternatives considered: We originally planned to write an ESLint rule to ensure that the variables that useEvent results are stored in are named {on,handle,set}XYZ, however solving this through seemed to better fit the semantics.
   3. Future: we might be a bit less strict about Promise and actually allow void | Promise<unknown>.
3. We forked eslint-plugin-react-hooks to treat the return values of these new hooks as stable when it comes to exhaustive-deps.
4. We then went through our codebase and replaced each const {on,handle,set}XYZ = useCallback with useEvent. A few cases were pointed out where the callback actually returned a value and needed to be replaced useEventWithResult.

Learnings:

1. Our codebase now roughly has a 1:4 share of useCallback to useEvent (120 vs 430).
   1. It means in those 430 cases we were able to remove the deps array.
   2. Because of the void-constraint we are very sure that this was correct semantically.
2. The term useEvent is still a bit odd.
   1. Intent is a bit unclear.
   2. Conflict with the concept of "events" (we had to renamed a different hook to useDOMEvent).
   3. Future: If React would not implement this RFC, we'd consider switching to useHandler (or useEventHandler) and useHandlerWithResult as a nod to the class-based component convention of naming event handlers (fun fact: in C# an EventHandler is required to be void as well).

[jampy]

Our signature requires that the callback's return type must be (async) void.

IMHO the question useCallback vs useEvent is not about the return type.

As @gaearon says:

In most cases, only the final consuming side (e.g. the Effect from which the event function is called) can be "sure" whether it "cares" about the reactivity of the function value.

I second that. It's not about the implementation. It's about the consumer.

[yolio2003]

what about useNonReactiveHandler

[sgarcia-dev]

@mrcljx your findings are really interesting. It's great to see that even if the RFC isn't finalized, the core idea behind this is beyond a POC and viable with the correct usage.

3. We forked eslint-plugin-react-hooks to treat the return values of these new hooks as stable when it comes to exhaustive-deps.

Do you mind sharing how you achieved this? We're curious to try this out but couldn't quite figure out the change necessary for this to work. The isStableKnownHookValue appears to be the function in charge of marking dependencies as safe to ignore.
https://github.com/facebook/react/blob/c635807875630e7057777e898372eed43e3b0a24/packages/eslint-plugin-react-hooks/src/ExhaustiveDeps.js#L164

Did you just add an additional scenario around the following line with code similar to this and re-build the extension?
https://github.com/facebook/react/blob/c635807875630e7057777e898372eed43e3b0a24/packages/eslint-plugin-react-hooks/src/ExhaustiveDeps.js#L226-L228

if (name === 'useEvent' && id.type === 'Identifier') { // "useEvent" being the name of the custom hook
  return true
}

Thanks!

[mrcljx]

@sgarcia-dev Yes, this is our patch (we also patched in useLatest which returns a Ref like useRef).

         }
         const id = def.node.id;
         const { name } = callee;
-        if (name === "useRef" && id.type === "Identifier") {
+        if (name === "useLatest" && id.type === "Identifier") {
+          // useLatest() return value is stable.
+          return true;
+        } else if (name === "useEvent" && id.type === "Identifier") {
+          // useEvent() return value is stable.
+          return true;
+        } else if (name === "useRef" && id.type === "Identifier") {
           // useRef() return value is stable.
           return true;
         } else if (name === "useState" || name === "useReducer") {

[zhangfisher]

Every additional API increases the mental burden on users

Now, users have to worry about when to use useCallback and when to use useEvent.

The two functions are quite similar, why not upgrade useCallback to have the useEvent function by default or through option switches?

I suggest considering enhancing the functionality of existing APIs while maintaining compatibility and asymptotic behavior.

[skyboyer]

has there been new RFC created? Can it be linked to this one? A lot of materials - quite outdated, yes - refer this current RFC. And without follow-up link it's just a dead-end

[dante01yoon]

Where can I find further discussion? Any updates here? and what's the progress?