Flicker-free mobile formatting toolbar: CSS variables + VirtualKeyboard API

[Movm]

Summary

We built an alternative mobile formatting toolbar positioning approach that eliminates the flickering from ExperimentalMobileFormattingToolbarController. We're using it in production with BlockNote v0.47.3 and would be happy to contribute it as a PR.

Problem

The current ExperimentalMobileFormattingToolbarController (introduced in #1284) uses React state (setTransform) on every visualViewport event. Each state update triggers a React re-render, causing visible flickering as noted in the code comments. This also relates to:

• Format toolbar goes offscreen on mobile #938 — Formatting toolbar goes offscreen on mobile
• iOS Safari: On text selection two overlapping menus #2122 — iOS Safari: overlapping menus on text selection

Approach: Industry-standard visualViewport + CSS variable

Instead of React state, we update a CSS custom property directly on the DOM — zero re-renders, the browser compositor handles repositioning.

Tier 1: VirtualKeyboard API (Chrome/Edge 94+, Samsung Internet)

Gives exact keyboard geometry with no delay — toolbar is positioned before the keyboard animation starts:

const vk = (navigator as any).virtualKeyboard;
if (vk) {
  vk.overlaysContent = true;
  const onGeometryChange = () => {
    wrapper.style.setProperty(
      '--mobile-keyboard-offset',
      `${vk.boundingRect.height}px`
    );
  };
  vk.addEventListener('geometrychange', onGeometryChange);
}

Tier 2: Visual Viewport API fallback (Safari iOS, Firefox)

The industry-standard approach with focus-based prediction for the initial keyboard open:

const vp = window.visualViewport;
let lastKnownKeyboardHeight = 0;

const update = () => {
  const bottom = window.innerHeight - (vp.height + vp.offsetTop);
  if (bottom > 50) lastKnownKeyboardHeight = bottom;
  wrapper.style.setProperty(
    '--mobile-keyboard-offset',
    bottom > 0 ? `${bottom}px` : '0px'
  );
};

// Predict on focus — apply last known height immediately
document.addEventListener('focusin', (e) => {
  const t = e.target as HTMLElement;
  if (t.isContentEditable && lastKnownKeyboardHeight > 0) {
    wrapper.style.setProperty('--mobile-keyboard-offset', `${lastKnownKeyboardHeight}px`);
  }
});

document.addEventListener('focusout', () => {
  wrapper.style.setProperty('--mobile-keyboard-offset', '0px');
});

vp.addEventListener('resize', update);
vp.addEventListener('scroll', update); // handles iOS URL bar collapse

CSS

@media (max-width: 767px) {
  .bn-formatting-toolbar {
    position: fixed;
    bottom: var(--mobile-keyboard-offset, 0px);
    left: 0;
    right: 0;
    padding-bottom: calc(0.375rem + env(safe-area-inset-bottom, 0));
    transition: bottom 0.15s ease-out;
    touch-action: none;
    z-index: 50;
  }
}

Key differences from current implementation

Aspect	ExperimentalMobileFormattingToolbarController	This approach
Positioning	setTransform() → React state → re-render	style.setProperty() → CSS variable → compositor
Re-renders per keyboard event	1 per event (10-20 during animation)	0
VirtualKeyboard API	Not used	Primary path on Chrome/Edge
Initial delay	Toolbar jumps from 0 to final position	Focus prediction applies last known height instantly
URL bar handling	Uses window.innerHeight only	Subtracts visualViewport.offsetTop per standard
Safe area (notch)	Not handled	env(safe-area-inset-bottom)
Touch handling	Not handled	touch-action: none prevents scroll interference
Transition	None (causes flicker)	150ms ease-out (smooth slide, only needed on fallback path)

Browser support

Browser	API used	Quality
Chrome/Edge Android 94+	VirtualKeyboard — instant, exact	Best
Samsung Internet	VirtualKeyboard (Chromium-based)	Best
Safari iOS 13+	Visual Viewport + focus prediction	Good
Firefox Android 68+	Visual Viewport + focus prediction	Good

What major editors do

Editor	Approach
WhatsApp Web	position: fixed + visualViewport resize
TipTap (mobile)	Floating toolbar via visualViewport (tiptap#6571)
WordPress Gutenberg	Toolbar sticky under header, not over keyboard (gutenberg#7479)
Notion	Native app → InputAccessoryView (not a web problem)

Contribution

Happy to submit a PR with a MobileFormattingToolbarController component in packages/react/src/components/FormattingToolbar/. Would keep the existing experimental controller untouched. Can coordinate with #2591 (portal floating UI to body) if needed.

We've been testing this in production on Android Chrome and Samsung Internet — works smoothly. iOS Safari testing is pending but the Visual Viewport fallback follows the established pattern.

[YousefED]

Seems great, thanks for the write up. Would gladly incorporate this as long as it also has iOS safari support. Looking fwd to a PR!

[Movm]

Thanks! Here it is: #2617