Escape Hatches - discussion (2023-01-11)
The "escape hatches" section is where a lot of codebases quietly live, even when they talk like everything is pure declarative UI. I'm curious which escape hatches people consider "normal integration" vs which ones they treat as a last resort that needs extra evidence and guardrails.
Which escape hatches do you reach for most often (refs, effects, imperative handles, manual DOM measurements), and how do you make them safe? What do you render as evidence so imperative work isn't invisible? Where have escape hatches bitten you (stale refs, layout thrash, focus bugs), and what conventions helped?
Comments (12)
Back to latestThe main rule we use: if it's imperative, it must be observable.
Even if users never see it, we render a debug line or data attribute so we can prove it ran.
Refs are fine, but focus management is where it gets spicy.
If focus jumps, users call it a bug even if it's technically "working".
We standardized on imperative handles for a few components (editor, media player) but only with a named surface and evidence.
tsx
export type PlayerHandle = { play(): void; pause(): void; seek(ms: number): void };
export const Player = forwardRef<PlayerHandle, { src: string }>(function Player({ src }, ref) {
const videoRef = useRef<HTMLVideoElement | null>(null);
useImperativeHandle(ref, () => ({
play: () => videoRef.current?.play(),
pause: () => videoRef.current?.pause(),
seek: (ms) => (videoRef.current ? (videoRef.current.currentTime = ms / 1000) : undefined),
}), []);
return <video ref={videoRef} src={src} />;
});Then the parent renders data-player-state so the imperative calls aren't invisible.
Counterpoint: imperative handles can be a slippery slope into building a second component API.
We prefer exposing state + callbacks unless the integration truly requires imperative control.
Agree. If the handle surface isn't stable and documented, it becomes "just call methods" and you lose the render contract.
When we do it, it's only for components that are already basically wrappers around imperative systems.
Layout measurement escape hatch: we render the measured values as evidence.
If your app measures DOM and nobody can see what it measured, debugging is miserable.
The docs posture around "make motion visible" applies here too.
Related: Testing and Debugging and Performance and Rendering.
Escape hatches have bitten us mostly in effect cleanup (dangling listeners) and in "measure then set state" loops.
Our fix was to centralize those in one module and treat them as infrastructure, not app logic.
We also render an "imperative ops" counter behind a flag (how many focus sets, scroll sets, etc.).
It's surprisingly useful for catching loops.
One rule: imperative work can't be the only source of truth.
If you scroll something into view, also update state so the UI can explain why it scrolled.
I wish more teams treated escape hatches as normal engineering instead of shameful hacks.
If you make them observable and constrained, they're just integration points.
Stale refs are the one that keep biting us: a handler closes over a ref that changed shape.
We fixed it by treating ref contents like an interface and versioning it (even if it's just a string key).
If you're using escape hatches, make sure you can explain them via a screenshot. Otherwise you're building invisible behavior.