Why a Tiptap focus callback fired before anyone touched the writing box

The toolbar’s three buttons, bold, italic and link, were open the moment the page loaded, before anyone had clicked in the writing box. The cause was the focus callback from Tiptap, the tool that turns the box into a small word processor. It fired once while the editor was still building itself, and that single early “yes” told the page the box was active when nobody had touched it.

It was only a strip of three kinds of buttons, but that strip was supposed to answer a simple question: is someone using this box right now? When it said yes before anyone had done anything, the page felt careless.

We had set it up the obvious way. Tiptap offered a focus callback, a message it sends when it thinks the writing box has become active. The name sounded exactly right. When the box gets focus, show the toolbar. When it loses focus, hide the toolbar.

That was the whole plan. No fancy trick. The page kept a simple yes or no note, and the toolbar followed that note.

Then the page loaded with the answer already set to yes.

Our first answer was to ignore the early message. We added a note saying, in effect, “Do not believe the first focus message until the editor has finished setting itself up.” A timer could do it. A small flag could do it. The first call would be brushed aside.

It worked, in the sense that the toolbar stayed shut on load. But it only taught the page to hope the software always starts in the same order.

It is like putting a piece of tape over the “check engine” light in a car because it comes on when you turn the key. The light is not the trouble. You need to know what it is reporting, and when. If the car changes how it starts next year, the tape does not become wiser. It just hides the next problem.

The same thing was happening here. During setup, Tiptap was either putting focus on the editor itself or reporting that focus had changed. From the page’s point of view, both situations arrived as the same friendly little message. The toolbar did exactly what we told it to do. It opened.

The cost of the timer was time, later. A timing trick can sit unnoticed until the software changes its starting routine. Then the toolbar can flash open again, and someone spends another afternoon wondering why a page that worked yesterday is acting strange today. It saves a few minutes now and leaves a puzzle for later.

Listening to the box itself

So we stopped listening to the message from the tool and listened to the writing box.

Every page has an actual spot where the cursor goes. Here it was the editable box that Tiptap placed on the page, and the browser can say when that box receives focus. That signal sits closer to the thing a person can see and touch.

We connected the toolbar to that browser event instead. We also made sure the listener was removed if the editor was replaced, so old listeners would not pile up on old boxes. The change was short, but it changed the question the page was answering.

Before, the page asked, “Did the editor software report a change in its focus state?” Afterward, it asked, “Did this actual writing box receive focus?”

Those are not always the same question.

What it does and does not prove

There is one limit worth keeping. A browser can put focus in a box because a person clicked it, but a program can move focus there too. So the new setup does not prove that a human hand caused every focus event. What it did do on this page was leave the toolbar shut while the editor was building itself, then open it when the box later received focus. That was the behavior the page needed.

The result was undramatic. The toolbar stayed closed until someone clicked into the writing area, which is all it was ever meant to do.

I would carry this past the writing box. Software often hands us a button, a label or a message with a friendly name. “Ready.” “Updated.” “Focused.” Those names feel like plain English, but they can describe the software’s own housekeeping rather than anything a person did. Here, “focus” meant the editor’s setup, and the fix was to follow the browser’s focus event on the one element a person can click. If we build something important on top of that gap, the screen can tell a believable little lie.

dxdev LESSON · paste into your AI coding agent
LESSON: A library's named callback describes its own internals, not necessarily the user's action
SOURCE: dxdev.com/everyday-ai/toolbar-that-turned-on-before-anyone-asked
WHAT HAPPENED: A rich-text editor's formatting toolbar was visibly open the instant a page loaded, before any user had clicked into the writing area. The code trusted Tiptap's focus callback to toggle toolbar visibility, but that callback also fires during the editor's own internal setup, not only on genuine user interaction, so the page treated its own initialization as if a person had already clicked in. The fix stopped listening to the library's focus callback and attached a listener directly to the underlying DOM element's native focus event instead, a lower-level signal closer to what the browser itself considers a focus change, with the listener cleaned up when the editor is replaced.
THE RULE: A friendly-sounding library event name, like "focus" or "ready," can describe the library's own internal state changes as much as an actual user action. When a UI decision depends on whether the user did something, verify against the lowest-level signal available rather than trusting the library's own report of it.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
  1. Any UI state, toolbar visibility, active badges, or ready indicators, driven directly by a third-party library callback without confirming that callback fires only on genuine user action.
  2. Any focus or blur-driven UI logic that does not clean up its event listener when the underlying element is replaced or destroyed.
  3. Any place a timing workaround, a delay, or a flag suppressing the "first" event was used to paper over a callback firing at the wrong time, instead of switching to a more accurate underlying signal.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.