DEV Community: Kyoko Otonashi

dvh Is Not a Keyboard Fix: Picking the Right Viewport Tool on Mobile

Kyoko Otonashi — Fri, 13 Nov 2026 10:01:16 +0000

100dvh fixed the old 100vh address-bar problem, and a lot of us quietly started treating it as "the mobile viewport fix." It isn't. It fixes one of the things that make a mobile web app's layout jump around. The on-screen keyboard is a different problem, and on iOS Safari dvh doesn't react to it at all.

This post is a decision table: which tool handles which mobile layout problem, and where it's easy to reach for the wrong one.

Four problems that look like one

When a full-height mobile layout breaks, it's usually one of these:

Browser chrome — the address bar and toolbar expand and collapse as you scroll.
The soft keyboard — it slides up and covers the bottom part of the screen.
Safe areas — the notch, the rounded corners, the home indicator.
Overlays that must stay reachable — bottom sheets, sticky toolbars, "Send" buttons.

They all show up as "my bottom bar is in the wrong place," so it's tempting to throw one fix at all of them. They need different tools.

What svh, lvh and dvh actually track

The viewport units are about browser chrome only:

svh — height when the browser UI is fully expanded (the small viewport)
lvh — height when the browser UI is retracted (the large viewport)
dvh — whatever it is right now, updating as the UI expands and collapses

That's it. None of them are defined in terms of the keyboard.

On iOS Safari, opening the keyboard doesn't resize the layout viewport. The keyboard overlays the page and only the visual viewport shrinks. So 100dvh stays the same height while the bottom of your layout is now behind the keyboard.

Chrome on Android behaves the same way by default these days (the keyboard resizes the visual viewport, not the layout viewport). There you can opt into the old "resize everything" behavior with the interactive-widget key:

<meta name="viewport"
      content="width=device-width, initial-scale=1, interactive-widget=resizes-content">

Safari doesn't support interactive-widget, so you can't rely on it for iOS.

The decision table

Problem	Tool	Notes
Address bar / toolbar changing height	`svh` / `dvh`	`svh` as a stable floor, `dvh` when the layout should follow the chrome
Soft keyboard covering content	`window.visualViewport`	The only cross-browser signal that includes the keyboard
Notch / home indicator	`env(safe-area-inset-*)`	Needs `viewport-fit=cover` in the viewport meta
Bottom sheet or toolbar that must sit above the keyboard	`visualViewport` + a CSS variable	Only for the components that need it
Keyboard geometry in Chromium	VirtualKeyboard API	`env(keyboard-inset-height)`; not available in Safari

A sane CSS default

For the app shell, start with plain CSS and no JavaScript:

.app-shell {
  min-height: 100svh;  /* stable floor */
  min-height: 100dvh;  /* follow browser chrome where supported */
  padding-bottom: env(safe-area-inset-bottom);
}

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

A couple of choices worth making on purpose:

height vs min-height. For document-like screens (articles, settings), min-height lets content grow. For a viewport-bound app UI (an editor with fixed chrome, a chat screen), you usually want a strict height and an inner scroll container.
dvh everywhere has a cost. dvh changes while the browser UI animates during scroll, so every element sized with it relayouts during that animation. Use it for the shell, not for every card.

The keyboard: visualViewport, scoped

When something genuinely has to stay above the keyboard, measure the visual viewport and expose it to CSS:

const vv = window.visualViewport;

function updateKeyboardInset() {
  if (!vv) return;
  // How much of the layout viewport is hidden below the visual viewport.
  const hidden = window.innerHeight - vv.height - vv.offsetTop;
  document.documentElement.style.setProperty(
    '--keyboard-inset',
    `${Math.max(0, hidden)}px`
  );
}

vv?.addEventListener('resize', updateKeyboardInset);
vv?.addEventListener('scroll', updateKeyboardInset);
updateKeyboardInset();

.composer-toolbar {
  position: fixed;
  left: 0;
  right: 0;
  bottom: var(--keyboard-inset, 0px);
}

Treat the number as an approximation. It moves during the keyboard animation, pinch-zoom changes it too, and the exact values differ between a Safari tab and a home-screen web app. Keep this logic to the one or two components that really need it instead of driving the whole layout from it.

The case dvh and visualViewport both miss

There's one more iOS behavior worth knowing: with the keyboard open, Safari can scroll the document itself, and position: fixed elements move with it. Whether that happens often depends on something boring — whether your inner scroll container still has room to scroll. If it doesn't, the gesture falls through to the document.

I wrote up that one separately, with a one-line CSS fix: The iOS Safari keyboard scroll bug, fixed with one line of CSS.

A real-device test pass

Simulators are fine for a first look, but keyboard and safe-area behavior needs a real phone. A quick pass that catches most of these bugs:

Load the screen, scroll so the browser UI collapses, then expands again.
Focus the bottom-most input. Is it visible? Is the toolbar still reachable?
With the keyboard open, try scrolling short content and long content.
Rotate the device with the keyboard open.
Repeat in a Safari tab and as a home-screen web app.
Check the bottom edge against the home indicator.

Takeaway

dvh is the right tool for the address bar and nothing else. For the keyboard, reach for visualViewport, and only in the components that need it. For the notch, env(safe-area-inset-*). Most "mobile viewport" bugs get easier once you figure out which of the four problems you're actually looking at.

I deal with this while building PenPage, a free, local-first Markdown notes app that runs in the browser. Notes stay on your device. Disclosure: it's my project.

This article was drafted with AI assistance.

The iOS Safari keyboard scroll bug, fixed with one line of CSS

Kyoko Otonashi — Wed, 12 Aug 2026 09:30:01 +0000

If you build a full-screen mobile editor as a position: fixed overlay with a fixed toolbar on top and a nav bar on the bottom, iOS Safari will happily scroll your entire chrome off-screen the moment the soft keyboard opens — but only when the content is short. The fix isn't a JavaScript viewport dance. It's one line:

.editor .ProseMirror {
  padding-bottom: 60vh;
}

Give the inner scroll container something to scroll, and iOS keeps the scroll inside it instead of falling back to scrolling the document (which drags your "fixed" elements along). No html/body locking required.

I hit this while building the mobile editor for PenPage, a local-first WYSIWYG markdown notes app (React + TipTap/ProseMirror). Everything below is verified on a real iOS device.

The setup

Picture a mobile note editor that takes over the whole screen:

┌──────────────────────────┐
│  Toolbar   (absolute,top) │  ← stays put
├──────────────────────────┤
│                          │
│  Editable content        │  ← scrolls
│  (overflow-y: auto)      │
│                          │
├──────────────────────────┤
│  Nav bar (absolute,bottom)│  ← stays put
└──────────────────────────┘

The outer container is position: fixed; inset: 0. The toolbar and nav bar are position: absolute inside it. The middle is the only thing that scrolls. Standard app-shell layout. Works great on desktop and Android.

The symptom

Tap into the editor, the iOS keyboard slides up, and:

Long document (taller than the viewport): perfect. The content scrolls under the keyboard, the toolbar and nav bar stay nailed in place.
Short document (shorter than the viewport): broken. Trying to scroll drags the whole screen — toolbar and nav bar included — as if the entire fixed overlay were a normal scrolling page.

That "only when short" detail is the whole story.

The root cause

This is the long tail of WebKit bug #191204: when the soft keyboard appears, iOS Safari's layout viewport gets shorter than the visual viewport, and the document itself becomes scrollable by the keyboard's height. Worse, in that state position: fixed / position: absolute elements stop being pinned to the viewport and start moving with document scroll.

Here's the key insight about when it bites you:

When your inner scroll container has room to scroll, the touch gesture is consumed there. iOS never needs to escalate to the document. Your fixed chrome stays put.
When the inner container has nothing to scroll (short content fits in the keyboard-shrunk viewport), iOS falls back to scrolling the document — and now the buggy viewport state takes over and your "fixed" toolbar and nav bar slide away.

So "long content works" was never luck. The long content was quietly absorbing the scroll the whole time.

The fix everyone reaches for (and why we skipped it)

The canonical workaround is the app-shell lock: pin html and body to the viewport so the document can't scroll at all, then move scrolling into an inner wrapper.

@media (orientation: portrait) {
  html.app-shell, html.app-shell body {
    position: fixed;
    inset: 0;
    overflow: hidden;
    overscroll-behavior: none;
  }
}

It works. We use exactly this in the project's legacy editor. But it's invasive: you're globally locking the page, you have to add/remove the state around mount/route changes, and it interacts with scroll-restoration, :has() scoping, and every other overlay you have. For a brand-new, self-contained overlay it felt like a sledgehammer.

The fix that actually shipped

Since the real trigger is "the inner container has nothing to scroll," the cure is to make sure it always does. Add a tall chunk of empty, scrollable space to the bottom of the editable area:

.editor .ProseMirror {
  min-height: calc(100dvh - 200px); /* fill the viewport so taps land in the editor */
  padding-bottom: 60vh;             /* always-present scroll headroom */
}

Now even an empty note has 60vh of scrollable runway below the cursor. The inner container is always scrollable, iOS never escalates to document scroll, and the toolbar/nav bar stay frozen. No JS, no global locks, no lifecycle wiring.

A nice bonus: because the padding is inside the contenteditable box, tapping that empty space still focuses the editor and drops the caret at the end — it reads as "tap below the text to keep writing," exactly like a native notes app.

Tuning the number

We trialed it live with a translucent red background on the filler so we could see it:

/* debugging only */
.editor .ProseMirror::after {
  content: '';
  display: block;
  height: 100vh;
  background: rgba(255, 0, 0, 0.12);
}

100vh — fixed the bug, but you can scroll the whole note completely off the top of the screen. Disorienting.
80vh — better.
60vh — the sweet spot: enough headroom to lift the caret line above the keyboard, not so much that the content vanishes.

Then drop the debug background and fold it back into a plain padding-bottom.

Caveats

The filler must live inside the element that scrolls (here, the contenteditable), not in some outer wrapper. The point is to keep that container scrollable.
vh vs dvh: we used vh for the filler (a fixed, generous amount is fine) and dvh for min-height (so the editor fills the dynamic viewport). Mixing them on purpose.
This addresses the scroll-hijack symptom. There's a sibling bug at the moment you enter editing — see below.
Tested on iOS Safari. Android/desktop never had the bug; the extra padding is harmless there.

The sequel: the toolbar still jumps on tap-to-edit

The filler kills the gesture-scroll hijack. But there's a second, sneakier trigger with the same victim (the top toolbar) and a different cause.

Our editor is always-editable: "view mode" is just the editor unfocused (no keyboard), "edit mode" is focused. Now try this: in view mode, tap low on the screen — in the bottom third that the keyboard is about to cover — to start editing there. iOS pops the keyboard and, because your caret is now underneath it, auto-scrolls the caret up into the visible band. That scroll is focus-time keyboard-reveal scroll, not a touch gesture — so the filler never gets a chance to absorb it. It shifts the whole layout viewport, and your position: absolute toolbar rides off the top edge. (Scroll back down, or blur, and it returns — classic #191204 transient.)

The caret landing above the keyboard is exactly what you want. The only defect is the toolbar going with it.

Fix: pre-scroll on focus, so iOS has nothing to reveal

The reveal-scroll only fires because the caret is under the keyboard. Remove the reason and you remove the effect: on the view→edit transition (i.e. on focus), synchronously scroll the inner container so the tapped line sits at ~1/3 of the viewport height — comfortably above where the keyboard will land. When iOS then evaluates "is the caret visible?", it already is, so its reveal-scroll is a no-op and the layout viewport never shifts. The toolbar doesn't move at all — no visible jump-and-correct, unlike compensating after the fact with a margin-top nudge.

Two implementation notes that make it robust:

Use the tap coordinate, not the selection. Record the pointer's clientY on a passive pointerdown on the scroll container (passive = never preventDefault, so it can't swallow your other touch gestures). The tapped Y is where the caret will land — you don't need to resolve it to a document position, and you dodge the "has ProseMirror synced the selection yet on focus?" timing question.
Scroll synchronously in the focus handler, before the keyboard animates in. scrollTop is instant; the reveal-scroll happens later, tied to the keyboard geometry. You win the race by construction.

const pendingTapY = useRef(null)

// passive: records where the tap landed, never blocks a gesture
scroller.addEventListener('pointerdown', (e) => { pendingTapY.current = e.clientY }, { passive: true })

// runs on the editor's / textarea's focus (the view→edit transition)
function preScrollIntoSafeZone() {
  const tapY = pendingTapY.current
  pendingTapY.current = null            // consume, so non-tap focus won't trigger it
  if (tapY == null) return
  const vh = window.visualViewport?.height || window.innerHeight
  if (tapY < vh * 0.55) return          // upper half is already visible; leave it
  scroller.scrollTop += tapY - vh / 3   // lift the tapped line to ~1/3 height
}

0.55 and 1/3 are feel-tuned on-device. The filler from the first half of this article is what guarantees there's always room to do this scroll.

Same principle, restated: the first fix keeps iOS from escalating a gesture scroll to the document; this one keeps iOS from needing a focus scroll at all. Two triggers, one victim, two one-liners — no html/body lock, no viewport-metric reflow tricks (those don't work; the WebKit metric is already corrupted by the time your JS runs).

Takeaway

When iOS Safari's keyboard scrolls your fixed UI away, don't assume you need the heavy app-shell html/body lock. First ask: does my inner scroll container always have room to scroll? If short content can leave it un-scrollable, a generous padding-bottom on the scrollable element is often the entire fix — one declaration, zero JavaScript.

I ran into all of this building PenPage — a free, local-first WYSIWYG markdown editor that runs entirely in your browser (no sign-up, notes stay in IndexedDB). If you try the mobile editor, everything in this article is what keeps the toolbar from flying away.