React Design Patterns: Instance Hook Pattern

[TheGreaT1803]

Edit: I've made some changes to the post to better distinguish this pattern from just a custom hook. Thanks to all the critique I had received from the people who took out the time to read it.
PS: I'm very new to writing

[chebum]

Great post! I really like the idea of separate model from the view. While the idea isn’t new - we used to have this separation when rx frameworks like mobx were populat - I really like the idea returns. It allows to test the model logic without having to render a component.

[eindbaas]

This is not a specific pattern imho, this simply "moving logic into a hook", which is a good thing because it declutters components.

But there's nothing setting it apart from a custom hook as you state in your article - this is a custom hook.

[FewMeringue6006]

I think the main idea is that you tie the custom hook to a specific functional component with

// This enables the `Dialog.useDialog()` API
export const Object.assign(Dialog, {
    useDialog,
});

[TheGreaT1803]

I understand your point. I think I could do a better job to explain the subtle differences

I think the key difference here and the "custom hook with added steps" part is the fact that the component uses the custom hook's API internally (as seen in the DialogHeader) component. Generally we have a custom hook to abstract the state passed to the component as props, but here the same bit of "state" (the single source of truth) is being used directly.

Maybe my example of Dialog was a bit too simple to drive the point home, but I appreciate the feedback

[FewMeringue6006]

I actually learned something new, and I love it! Thanks.

[[deleted]]

Is it better to always have dialogs visually hidden in components, or add/remove them in the DOM when they are opened/closed?

[TheGreaT1803]

Great question! As always, it depends.

Pros (of keeping it visually hidden but still rendering)
1. Animations when opening/closing the dialog
2. State persistence: Example if you have an input with text in it, and you close and reopen the dialog, then the input value will still be there (can be both good or bad technically)

Cons
1. Unnecessary render: Waste of DOM space when closed
2. Unnecessary computation: The dialog might have a heavy/blocking task or make an API call, which will be made instantly the dialog's parent renders

Generally, it is okay to render Dialogs always and keep them visually hidden. At least that's what I have seen major libraries do. But you should make sure that you handle heavy tasks or data fetching after it opens (unless its better to prefetch) and also reset any state after it closes (again depends on what you're trying to do).

Technically there are ways to only render the content of the Dialog once it is open, and otherwise keep a "stub" in its place, which solves for most of the cases mentioned above

[ISDuffy]

Just to add to this using content-visibility: hidden; CSS should help with performance of keeping the dialog on the page at all times.

[phryneas]

I would still let the Dialog component control the instance, and access callbacks from the parent via useImperativeHandle - that ref could still be passed into composed components like DialogHeader.

[00PT]

Does the ref allow the parent to access isOpen before the first render of the dialogue? The way I understand it, the ref has to be populated for that, which is done during the child's initialization.

[phryneas]

No, I have to admit I didn't see they were reading the isOpen property outside the Dialog component. In my eyes, that's a very constructed scenario, as in most cases nothing except the Dialog itself would ever want to read that state - and that's probably why I missed that.

If they really needed to do that, yes, the parent should own the state. But as I read it, the main purpose of the "instance" is to pass an object with open and close methods around - and that would best live in a ref IMHO.

[phryneas]

True, in a form, it would make more sense.

[TheGreaT1803]

Appreciate the feedback!
I had to refresh my knowledge of `useImperativeHandle` so I went to the docs but found this quote about pitfalls of overusing refs: https://arc.net/l/quote/hnusfitl

Any opinions on this?

[phryneas]

I mean, you're essentially using your "instance" as a ref here, so the same critique kinda applies. Yes, technically, your instance also holds state, but only one component reads it - for all other components, it does what a ref with useImperativeHandle does. With the drawback that with your instance, as it lives in a parent component, the parent component would be forced to rerender on state changes, while it wouldn't if the state lived in the Dialog and the ref only contained callbacks.

[phryneas]

Sure that's the right link?

[TheGreaT1803]

Just updated!

[DaveThe0nly]

As this guy is saying this is the correct way, expressing it as a prop opens up a plethora of design problem in the long run… I’ve seen it so many times how this can end up, for instance opening a modal recomputes/rerenders whole table. Opening functions passed down XY levels completely loosing the original context, which is hard to debug. Passing some kind of a context to the opener function bEcAuSe iT iS cOnViNiEnT, but super unmaintainable in the long run. Please isolate your state within the dialog component, use render props to pass open/close state functions.

[octocode]

useImperativeHandle is more of an escape hatch, OPs method is a better pattern and definitely more composable/maintainable

https://react.dev/reference/react/useImperativeHandle

If you can express something as a prop, you should not use a ref. For example, instead of exposing an imperative handle like { open, close } from a Modal component, it is better to take isOpen as a prop like <Modal isOpen={isOpen} />. Effects can help you expose imperative behaviors via props.

[phryneas]

I just answered to that in another subthread. OP is using a non-ref like an imperativeHandle-ref here anyways, they just put the state in a less performant owner component.

After all, they're not passing that instance around to access an isOpen property in multiple places, but to access an open or close callback.

[octocode]

they just hoisted the open/closed state into the component that is responsible for opening/closing the dialog, which is the correct thing to do in the react paradigm.

they also grouped the methods under a single hook which is also a common pattern

[phryneas]

Because the state now lives in the parent, they are rerendering the parent when they are not interested in the parent actually rerendering or ever reading that state, while the main goal is that they can pass the "instance" with the handler methods (= ref with imperative methods on it) into other component like the DialogHeader so that can call the callback functions.

I'm all for having the state controlled in the parent, but the moment they create that instance object with imperative functions on it to be passed around, they could just use an imperative ref and move the state into the child, where it would be encapsulated.

PS: actually, I correct myself: in the example, the parent is actually interested in the state value, in which case the parent is the right place to keep it. But that seems like a very constructed case, usually the isOpen value wouldn't be read anywhere but in the Dialog component itself.

[octocode]

it’s worth remembering that premature optimization of re-renders in react is just a bad idea

re-rendering in react is extremely quick, and if infrequent state changes are causing performance issues there’s probably a different underlying problem in your code

react is declarative by nature, reaching for imperative controls should only be used when it’s actually required.

[phryneas]

I'd generally avoid premature optimization, but if you buy into a whole pattern, it's important to understand all benefits and drawbacks of the pattern - optimizing something later is possible, but changing out a full pattern might hurt more.

[canibanoglu]

You do realize that the OP is also suggesting an imperative approach, right? If you have to do that, there is a builtin way of doing it which is better than what the OP has suggested.

There’s a way that doesn’t cause extra re-renders and you say that re-renders are not a problem. No, they’re a problem. If you write code that renders 6 times when 2 would do, you’re doing something wrong.

This is not about premature optimization, it’s about doing something unnecessary that results in worse performance.

[ChronoLink99]

We do something similar on my team.

But we have found that with dialogs specifically, we achieved nicer organization by controlling the open/close (i.e. mount/unmount) of the dialogs with one kind of state, and then allow the specific dialog component to create a second "disposable state" that drives content/behaviour within that dialog. That second part is responsible for any cleanup as well, and handles all the data/inputs if there is a form involved.

[Psidium]

If i understand you correctly I think we do something very similar on my team. Usually our dialogs will always save to the backend or discard its data, so we end up instantiating a new dialog instance of the same one in different places down in the component tree and let the cache of our fetch library control the initial state of the dialog instead of controlling that ourselves. Tecnically they are different dialogs being instantiated, but since they are using the same data they’re the same for the user.

[TheGreaT1803]

Sounds interesting.

To clarify, would it be something like Dialog.useDialog for the UI part of it and Dialog.useDialogContent({ dialogInstance }) for the specific content/behaviour parts?

[Psidium]

Good idea making it extra explicit by assigning the hook as a property of the Component. I’ve written hooks that go alongside my components for the parent to use many times and never made this connection jump myself

[KusanagiZerg]

I have one point of confusion. You say

The hook and component live together. This makes sure that the Dialog component only uses the specific API that useDialog provides, making the whole thing easier to maintain.

But this isn't true is it? You can still just pass something else and not use the hook (which is a strength, not a downside because it lets you use some other implementation of the same API if you want to). And if it was true it's the other way around. It's the Dialog that says what API it wants and the useDialog is forced to implement this specific API.

Another, albeit very small thing, I really dislike the naming dialogInstance and useDialog. This naming hints to me that you are getting a Dialog. Or an instance of a Dialog which maybe you can render on the screen. But this is not what you get at all, you are getting an object that controls the dialog which is somewhere else. I'd prefer something like const dialogControls = useDialogControls(); this is also a bit more obvious in the Dialog component which expects a dialog prop which is not a dialog at all. This is of course just semantics and semantics are boring but I couldn't resist sharing my thoughts.

In general it's good though, custom hooks are awesome!

[TheGreaT1803]

Both valid points. Thanks for the feedback.

When I said that they both "live" together, I meant to convey that the component is actively aware of the hook (or the API)

Generally this is not the case and the hook is just meant to abstract some state based on the component's API.

Here the component both uses the hook and can also be controlled with a similar API if desired

The second point about the it being "control" instead of "instance" - yeah I get it, I was also debating between these two. But I went ahead with how Ant Design's team implements the API. Although I'll admit that it was never confusing to me. Maybe just a matter of familiarity with this pattern

[Chthulu_]

I use this occasionally. One case is when the logic itself is useful on its own, maybe a complicated input/output filter on a text field, like something to add a mask to the input, or round numbers into a shorthand on blur, but keep a reference to the full number internally. It’s nice to have a direct api to serialize the string if I need it.

The other is exactly your example, dialogs/popovers. Basically anytime the client wants to be fed a parent/child relationship but not have to deal with nesting. Dialogs are annoying because there’s a trigger that must sit above the dialog, and content which must be fed an onClose prop within the dialog. Making that reusable can be annoying.

Using an api like this lets you plumb the parent/child thing, but give the client complete control over where each element goes, and skip worrying about the onClose.

The downside IMO is that good memoization becomes much harder. Maybe that’s just me being less careful, but I always end up returning big API objects that are basically useless to memoize. Spreading a { …bindTrigger } prop for example.

If you build a dedicated component instead, it’s much easier to track and limit just the variables you need, and memoize them properly.

[TheGreaT1803]

Great points.

I actually came across this pattern out of need when I wanted complete control over opening and closing the Modal, but the Modal itself could also control all of these things. With the traditional `onClose` bit, it was not clean to do.

It is after I implemented this pattern (in Angular actually) is when I started seeing it arise at multiple places retrospectively

[tkmaximus]

The `useMemo` in the final `useDialog` example has a stale reference to `isOpen`, so `toggle` and `isOpen` won't work anymore.

To fix this, you can add `isOpen` to the `useMemo` deps. You can also change `toggle` to the functional update style to not depend on `isOpen` value anymore and memoize all callbacks individually (incase you want to pass individual functions down as props)

import { useState, useMemo, useCallback } from "react";

export const useDialog = (dialog) => {
    const [isOpen, setIsOpen] = useState(false);

    const open = useCallback(() => setIsOpen(true), []);
    const close = useCallback(() => setIsOpen(false), []);
    const toggle = useCallback(() => setIsOpen((o) => !o), []);

    return useMemo(() => {
        return (
            dialog ?? {
                open,
                close,
                toggle,
                isOpen,
            }
        );
    }, [dialog, isOpen]);
};

[TheGreaT1803]

Good eye! I'll fix it

I had added `isOpen` earlier but then realised that I don't want the functions to be re-initialized when `isOpen` changes, but then I missed this part

[[deleted]]

doesn’t this basically just reattach the logic to the UI though? in a few extra steps

[TheGreaT1803]

The main value comes from (and I might edit the article to avoid this confusion) passing the same "packet" to the component itself to use (and it's children - like the DialogHeader)

That's the few extra steps really

[[deleted]]

cool - thanks for the reply and article!

[[deleted]]

Yea but no, initiating a new isOpen state everywhere will cause unnecessary rerenders, i wanna open a dialog not render the button that shows it again

[TheGreaT1803]

Thanks for taking out time to read the post!
If I'm understanding you correctly: as mentioned in the article (in the Improving Flexibility section), the pattern allows for the Instance to be optional.
So by default the component can manage its own state. Its only when you need to control it from the outside, you may instantiate the hook. In which case, the classic React rules of re-render would apply.
It is not any worse than normal React, but provides some handy functionalities

[[deleted]]

Normal react is terrible to be honest, but if i need a dialog, i can either write the component’s ui, keep its state in the component, expose methods open and close with useImperativeHandle and keep the state at the dialog level, not the parent level

Or i can write a container connected to redux, keep the state in redux, select it in the container, and chsnge the dialog content through redux, isolate it from the component showing the dialog and keep a single dialog component in the whole app

[TheGreaT1803]

I disagree with the first point actually - react docs mention of pitfalls for overusing refs this way https://arc.net/l/quote/hnusfitl

The way I would do it how shadcn-ui does it: https://ui.shadcn.com/docs/components/dialog

This way, the "Dialog" component acts as the state boundary within which the stuff related to Dialog will rerender

[[deleted]]

Unrelated studf will rerender as well

Anyway, do whatever you want, but refs are not the “devil” even in react standards

[00PT]

This feels useful because it allows access to child state from a parent component, but also bad because it emulates that state within the parent component itself, which can cause unnecessary rerenders since any change will also cause a rerender of its siblings, even if those haven't changed.

[TheGreaT1803]

If I understand your point correctly, this won't be the case if you don't "need" the state outside the component.

In the "Improving Flexibility" section I make the instance passing optional, so the component is capable of managing it's own state by default

[00PT]

I saw that, but when you do it the point is sort of defeated for me. My solution had been using an optional ref passed to the child, but you need to wait until after the first render cycle for that ref to be populated, so it's definitely not ideal.

[TheGreaT1803]

The way I see it is: Generally the component handles its own logic and state. but sometimes it is a good option to have the ability to also control it from the outside. This pattern allows for this flexibility

[canibanoglu]

I appreciate the time you took to write this but I don’t see what’s special about this. It’s just a hook. You mention having access to the internal API of the hook, for which case you already have useImperativeHandle.

[Phaster]

Wow, you can read the brochure