A toast library you can call from anywhere, including outside React

embertoast is a toast library for React with one idea underneath it: the thing that produces a notification and the thing that draws it should not be the same thing. Calling code uses an ordinary function, from anywhere, including a module that has never heard of React. A single mounted component subscribes to a store and renders whatever is in it.

That split is not a style preference. It decides what the library can do: whether an error handler in a fetch wrapper can raise a toast, whether a promise can morph through its own lifecycle without being replaced, and whether a renderer for another framework is a new subscriber or a rewrite.

0

Runtime dependencies in either package

4.5 kB

Size budget for the React package, enforced in CI

65

Tests across the store and the renderer

The usual shape for this is a hook. A hook can only run inside a component during render, which means every notification has to originate from a component and thread context or a ref down to whatever draws it. The places that most want to raise a notification are exactly the places a hook cannot reach: a request interceptor, a websocket handler, a retry helper, a plain utility three files from any component.

The second problem is the promise. Nearly every library models a promise as three separate toasts, so a loading card disappears and a success card slides in behind it. The user sees a flit. What they should see is the same card changing its mind.

Once the store is a module-level singleton and the component is only a subscriber, a question appears immediately: where does a leave animation live? The store cannot own it. An exiting flag in the store would mean a dependency-free engine had to know about animation events, motion preferences and fallback timers, and worse, the snapshot would lie for a few hundred milliseconds about what is on screen.

So the store removes synchronously and stays honest, and the renderer grows a small presence layer that diffs the live list against the previous one. An id that just left is held mounted, marked as exiting, and retired when the animation reports it finished, with a timer as a backstop because a backgrounded tab may never fire that event at all. Re-adding the same id cancels an exit in flight. Under reduced motion the whole phase is skipped.

The other discovery was about directions. Writing positions as screen edges means writing mirroring twice. Writing them as the inline axis and putting the box geometry in logical properties means right to left is the same code path, and the only work left is reading the document direction and watching it for changes at runtime.

Nothing to the left of the store knows what a pixel is. Calling code talks to a facade, the facade talks to a store, and the store notifies subscribers. Everything to the right of the store is rendering, and everything to the left of it is a function call that could have come from anywhere.

Solid lines are calls. The dashed line is the subscription: the renderer is told that something changed and reads the new snapshot itself, which is what keeps the store free of React and makes a renderer for another framework a new subscriber rather than a rewrite. The dashed line back to the store is a toast item reporting a pause on hover, a resume on leave, or a dismiss on click.

The promise method is the only part of the facade with real logic. It opens one toast pinned open, keeps the id, awaits the promise, and on settle updates that same id with the new type and content. One id, one node, from loading straight through to success. The morph is the whole point: nothing is replaced, so nothing flits.

Reflow is the hot path, because when a toast leaves, the survivors have to move and they have to do it at frame rate. The renderer measures where each card is, lets layout settle, measures again, applies the inverting transform and then releases it, so only transform and opacity ever animate and the browser never lays out per frame. The collapsed deck uses scale, the swipe uses its own transform, and the reflow uses translate, which is why three gestures can share one element without one cancelling another.

Timers track elapsed time rather than being recreated, so a hover that pauses at 2.3 seconds resumes with 1.7 left rather than starting over. They also pause when the tab is hidden or the window loses focus, because four seconds that elapse while nobody is looking were never a notification.

The four calls that shaped the library. Every one buys something specific and charges for it somewhere else.

Accessibility is treated as a feature rather than a pass at the end. Each renderer owns one live region, and toasts are inserted into it so assistive technology announces them without the visual container deciding announcement order. Politeness follows severity: errors and warnings interrupt, everything else waits its turn. Focus is never moved, because a notification that takes the cursor out of a form is a bug wearing a feature's clothes, and an interactive toast is reachable by keyboard without trapping anyone in it.

Motion is a preference, not a default. Under reduced motion the enter, exit and reflow transitions collapse to nothing, and the presence layer skips its exit phase rather than waiting for an animation that will never play. The library is fully usable with every animation off, which is the actual test of whether motion was decoration or structure.

The tests split along the same seam as the code. The store's tests are plain unit tests with no DOM: ids, queue promotion, pause and resume arithmetic, the promise lifecycle. The renderer's tests cover what only exists once there is a document: the live region and its politeness, the mirroring, presence and reflow behaviour, and the swipe. The gesture is the one thing a unit test cannot honestly claim, so it is verified in real browsers, including mobile Safari, where pointer events behave least like the others.

There is a small discipline in the overflow rule that is easy to miss. Only a fixed number of toasts render per position and the rest queue, so a burst of twenty cannot bury the page, and promotion is first in first out so the order is something you can reason about rather than a race.

Most of the restraint in this library is about what the core is allowed to know. It does not know what a pixel is, whether a document exists, or that animations have durations. Every time something wanted to leak into it, that was the signal it belonged in the renderer instead, and the presence layer exists because of exactly one such attempt.

I also left out the temptation to ship adapters for other frameworks. The store makes them possible, which is the part worth claiming; shipping renderers I would not maintain would be a worse promise than not shipping them at all.

The useful lesson is how much a single boundary decides. Splitting the producer from the renderer answered questions I had not asked yet: where exit animations live, why the promise can morph, how another framework would attach, and what the core is allowed to import. When a design keeps answering later questions without being revisited, that is usually a sign the seam was cut in the right place.

The other lesson is that the unglamorous requirements are the ones that make a component library trustworthy. Announcing correctly, honouring reduced motion, pausing a timer when the tab is hidden and mirroring properly are not features anyone lists when they pick a toast library, and they are exactly what someone notices when they are missing.