The web VirtualKeyboard API with React
The web experimental VirtualKeyboard API promises control over what happens in our pages when interacting with inputs, let's test it with React.
Traditionally, web pages have layouts that are bigger in height than the viewport. Vertical scrolling is second nature to everyone. But in app-like designs, focused on interactivity, having fixed headers and footers is very common. Toolbars and inputs are expected to be visible all times. It works well in native iOS and Android apps, but how can it be translated to web browsers on mobile? This is where VirtualKeyboard API comes to help.
Notes:
We are going using Next.js and Android emulator for the tests
This API is considered experimental and is not supported on iPhones
Initial setup
For this test I choose to bootstrap the project with Next.js. It's a good baseline because it already has Tailwind configured, and it supports HTTPS by using the --experimental-https flag. This is important because the VirtualKeyboard API is only supported in secure contexts.
We can start creating our Next.js app:
npx create-next-app@latestI named the project virtual-keyboard-api-test and checked some options like using app router, src dir, TypeScript, and Tailwind. Then we can go to the package.json file to add the HTTPS flag:
{
...
"scripts": {
"dev": "next dev --turbopack --experimental-https",
"build": "next build",
"start": "next start",
...On your terminal you can run npm run dev to get the project started. It might ask for your password before being able to generate the certificates. It will add a certificates folder and add this folder to the .gitignore file.
After this you can click on the output to open the project in your browser. Note that it shows the option to open the project in the Network. We are going to use this URL with the IP on the Android Emulator later:
▲ Next.js 15.2.2 (Turbopack)
- Local: https://localhost:3000
- Network: https://192.168.15.9:3000For now let's open the project in the Desktop browser so we can create our testing layout.
Creating an 100% height layout
Some types of applications need full height layout. Think about a chat app like WhatsApp or Chat GPT, or a text editor app like Google Docs. The basic layout usually expects a fixed header and footer, some scrollable content between them and a text input. Let's create a page with this setup to see the issues that happen on mobile browsers when the virtual keyboard pops up.
For the page container we can use a flex column layout with 100% of the dynamic viewport height. The page will take all the available height accounting for when the address bar is open or closed on mobile (spoiler, it does not account for the virtual keyboard).
For the header and the footer we can add shrink-0 so they don't change their sizes. For the scrollable content we can use flex-grow to use all available vertical space and overflow-y-auto to scroll when needed.
Here is how the file src/app/page.tsx looks like:
'use client';
const contentArray = Array.from(Array(50).keys());
export default function Home() {
console.log('Home');
return (
/* Page container 100dvh (100% of the dynamic viewport height) */
<div className="flex h-dvh flex-col text-lg text-neutral-900">
{/* Header */}
<div className="h-16 shrink-0 bg-red-100 p-2">
Header (should always be visible)
</div>
{/* Scrollable content (takes available height) */}
<div className="flex-grow overflow-y-auto bg-blue-100 p-2">
{contentArray.map((item) => (
<p className="py-2" key={item}>
Scrollable content {item}
</p>
))}
</div>
{/* Footer */}
<div className="shrink-0 bg-green-100 p-2">
<div>Footer (should always be visible)</div>
<textarea className="w-full border border-neutral-800 bg-white px-2 py-1" />
</div>
</div>
);
}The issue on mobile
This is pretty basic and works as expected on the desktop. The header, where we could have a navbar or a toolbar, is always visible like we wanted. It's the same for the footer. In a chat app we would have the text input that also should always be visible.
But what happens on mobile browsers when the virtual keyboard appears? Here is a side by side comparison of Desktop Chrome vs Android Chrome:
The page is moved up out of the "camera" view to fit the virtual keyboard on mobile. The browser has two concepts for viewports, the layout viewport and the visual viewport. No resizing of the layout viewport happens, that's why we can't see the header anymore. The page does not shrink. It simply moves out of the "camera" creating a double scroll which is a really bad experience.
The header that has important navigation buttons is not accessible. Scrolling to show it is also bad. We need to go over all scrollable content to start scrolling the page.
Now there is a standard (but experimental) way to deal with this scenario, the VirtualKeyboard API. With this API we can do things like:
Show or hide the virtual keyboard with the
show()andhide()functionsOpt out of the automatic virtual keyboard behavior described above
Detect the virtual keyboard geometry with JavaScript
Detect it also with CSS environment variables
Fixing the problem
As of writing this post (17 Mar 2025) the VirtualKeyboard API is not available in Safari. This means it won't work on iPhones because all browsers on iOS use WebKit, so they behave like Safari. We can get updated info regarding the support of this and other APIs in Can I use. So let's focus our tests on Android Chrome.
Step 1 - opting out of the automatic virtual keyboard behavior
To avoid the problem shown in the video we need to opt out of the automatic behavior when the virtual keyboard is displayed. For this we can add an useEffect to check if the browser supports the VirtualKeyboard API and change the overlaysContent to true. As the name suggests it will make the virtual keyboard to show on top of the page, without changing the visual viewport height. It will simply overlay the page content.
Soon we will see that this doesn't fix the issue, it actually makes it worse, because the content will be hidden below the keyboard, including the text input. But we will get to it later.
So let's add our useEffect and enable the overlay:
...
import { useEffect } from 'react';
...
export default function Home() {
...
useEffect(() => {
if ('virtualKeyboard' in navigator) {
console.log('has VirtualKeyboard API');
// Make the virtual keyboard overlay the content
navigator.virtualKeyboard.overlaysContent = true;
return () => {
console.log('cleanup');
// Reset the virtual keyboard overlay setting
navigator.virtualKeyboard.overlaysContent = false;
};
}
console.log('no VirtualKeyboard API');
}, []);
return (
...TypeScript is not happy with navigator.virtualKeyboard. It has the Navigator interface, but it doesn't include the virtualKeyboard object. We are going to fix it later. We can still run our project with npm run dev.
After running our Android emulator from Android studio and opening our test page on Android Chrome, we can also open a new tab chrome://inspect/#devices on our Desktop Chrome, then open the debug view of the emulator.
As expected, the problem got worse, the keyboard is overlaying the input and we can't see what we are typing!
At least we are not getting the double scroll anymore and the layout viewport doesn't get pushed away from the visual viewport.
Step 2 - fixing TypeScript
Let's fix the types on the Navigator interface. We are going to include the virtualKeyboard in this interface.
File global.d.ts:
declare global {
interface VirtualKeyboardGeometryChangeEvent extends Event {
target: EventTarget & VirtualKeyboard;
}
interface VirtualKeyboard {
show(): void;
hide(): void;
readonly boundingRect: DOMRect;
overlaysContent: boolean;
addEventListener(
type: 'geometrychange',
listener: (event: VirtualKeyboardGeometryChangeEvent) => void
): void;
removeEventListener(
type: 'geometrychange',
listener: (event: VirtualKeyboardGeometryChangeEvent) => void
): void;
}
interface Navigator {
readonly virtualKeyboard: VirtualKeyboard;
}
}
export {};I saw that we have the types in a language called WebIDL on the W3C definition of the API. So I translated the WebIDL to TypeScript. I'm sure there are ways to improve it, but it's good enough for now.
The last step is to include it in our tsconfig.json file:
...
"include": [
"next-env.d.ts",
"global.d.ts",
"**/*.ts",
"**/*.tsx",
".next/types/**/*.ts"
],
...Step 3 - detecting changes
Now let's create a hook that detects when the virtual keyboard shows and hides. This can also be detected by CSS, but let's try JS first. We will add an event listener to notify when the keyboard geometry changes. The geometry is just a rectangle with x and y positions and width and height. When the virtual keyboard is hidden, it's just all zeros. Later we'll use the height when it pops up.
File src/hooks/use-virtual-keyboard-bounds.ts:
import { useEffect, useState } from 'react';
export const useVirtualKeyboardBounds = () => {
const [bounds, setBounds] = useState({ x: 0, y: 0, width: 0, height: 0 });
useEffect(() => {
if ('virtualKeyboard' in navigator) {
console.log('useVirtualKeyboardBounds: has VirtualKeyboard API');
// Make the virtual keyboard overlay the content
navigator.virtualKeyboard.overlaysContent = true;
const handleGeometryChange = (
event: VirtualKeyboardGeometryChangeEvent
) => {
// Update state when bounds change
const { x, y, width, height } = event.target.boundingRect;
setBounds({ x, y, width, height });
};
navigator.virtualKeyboard.addEventListener(
'geometrychange',
handleGeometryChange
);
return () => {
console.log('useVirtualKeyboardBounds: cleanup');
navigator.virtualKeyboard.overlaysContent = false;
navigator.virtualKeyboard.removeEventListener(
'geometrychange',
handleGeometryChange
);
};
}
console.log('useVirtualKeyboardBounds: no VirtualKeyboard API');
}, []);
return bounds;
};Importing it in the src/app/page.tsx file we get:
'use client';
import { useVirtualKeyboardBounds } from '@/hooks/use-virtual-keyboard-bounds';
const contentArray = Array.from(Array(50).keys());
export default function Home() {
const bounds = useVirtualKeyboardBounds();
console.log('Home - bounds:', bounds);
return (
...Now we can see that when the keyboard pops up React will update the state, so we can get the bounds:
Step 4 - making some deserved space
Our layout already has a resizable area (the scrollable content) which takes the available height. Now it's super simple to reserve some space for the keyboard when it pops up. We can just create a placeholder div and set the height that we are getting from the hook:
...
{/* Footer */}
<div className="shrink-0 bg-green-100 p-2">
<div>Footer (should always be visible)</div>
<textarea className="w-full border border-neutral-800 bg-white px-2 py-1" />
</div>
{/* Keyboard placeholder, it will grow to take virtual keyboard space when it appears */}
<div
className="shrink-0 bg-purple-500"
style={{ height: `${bounds.height}px` }}
/>
</div>
);
}This was our final peace, the placeholder div will be below the keyboard when it appears. This will make the scrollable content height to shrink when the placeholder grows and grow when the placeholder shrinks. The height of the page will be constant, and the only scroll area is in the scrollable content. No double scrolls.
Now our header and footer are both always visible:
Virtual keyboards reaches legal age
Since the first iPhone in 2007 the virtual keyboards are in the hands of almost every web user. It's incredible to think that we are in 2025 and there is no reliable way yet to control and detect changes in the virtual keyboard. I tried to find sources from Apple to see if they are working to implement this API, but I could only find this issue. Hopefully they will implement it someday!
Bonus - using CSS
Optionally we can use CSS environment variables to get the keyboard geometry like the keyboard-inset-height (see all variables). We would still need an useEffect to set the navigator.virtualKeyboard.overlaysContent flag, but we would not need to use the event listeners to get the height.
Here is how it would look like:
...
{/* Footer */}
<div className="shrink-0 bg-green-100 p-2">
<div>Footer (should always be visible)</div>
<textarea className="w-full border border-neutral-800 bg-white px-2 py-1" />
</div>
{/* Keyboard placeholder, it will grow to take virtual keyboard space when it appears */}
<div className="h-[env(keyboard-inset-height,0)] shrink-0 bg-purple-500" />
</div>
);
}This is a bit simpler, but we only have the value in CSS land, not React. The hook is useful if you wanna do more complex stuff.
Thank you all for reading this long post. Since I'm an Android user I'll integrate this solution in this very blog you are reading now. The Blog text editor needs it so I can better edit my posts from the phone! I'm looking forward to seeing it also on the iPhone, allowing us to make richer apps, and better experiences for the stuff that we use every day.
Bye, see you in the next one!