real-viewport-height

Maintains a CSS variable --real-vh with the actual visible viewport height.

*This documentation was written by an artificial intelligence and may contain errors or approximations.
It has not yet been fully reviewed by a human. If anything seems unclear or incomplete,
please feel free to contact the author of this package.*

Installation

``bash
npm i @itrocks/real-viewport-height
`

Usage

@itrocks/real-viewport-height keeps a CSS custom property --real-vh
in sync with the visible browser viewport height in pixels.

This helps you work around mobile browser issues where 100vh includes
the URL bar or on‑screen keyboard, which makes elements taller than the
actually visible area.

When the module is loaded in a browser environment, it:

- computes the current visible viewport height (using window.visualViewport
when available, falling back to window.innerHeight),
- writes that value as a pixel string (for example 640px) into the
--real-vh CSS variable on document.documentElement,
- keeps this variable up to date when the viewport changes because of
orientation changes, browser chrome appearance/disappearance, or the
virtual keyboard.

You typically only need to import the module once at the entry point of
your front‑end code, then consume --real-vh from CSS.

$3

`ts
// main.ts (or any front-end entry file)
import '@itrocks/real-viewport-height'

// No further JavaScript is required: just use the CSS variable.
`

`css
/ Use the real visible viewport height for a full-screen container /
.app {
height: var(--real-vh);
}
`

$3

In a typical SPA or mobile‑focused web app, you may want your main
screen to always fit the visible viewport, even when the on‑screen
keyboard opens.

`ts
// src/main.ts
// Import for its side effects so that --real-vh is maintained
import '@itrocks/real-viewport-height'

// Your usual application bootstrap code follows
import { createRoot } from 'react-dom/client'
import { App } from './App'

createRoot(document.getElementById('root')!).render()
`

`css
/ src/styles.css /

html,
body {
margin: 0;
padding: 0;
height: 100%;
}

/ Main viewport‑filling container /
.app-root {
/ Use the real, visible viewport height instead of 100vh /
min-height: var(--real-vh);
display: flex;
flex-direction: column;
}

/ A header with fixed height /
.app-header {
height: 56px;
flex: 0 0 auto;
}

/ Content area that adapts when the virtual keyboard appears /
.app-content {
flex: 1 1 auto;
overflow: auto;
}

/ Optional: use a fraction of the viewport height /
.half-screen-panel {
height: calc(var(--real-vh) * 0.5);
}
`

In this setup, the .app-root container always matches the visible
viewport height, and the content area scrolls naturally when the virtual
keyboard is shown.

API

Although this package does not export named functions for you to call
directly, it exposes the following observable behavior and values.

$3

CSS variable defined on document.documentElement with the current
visible viewport height in pixels.

- Location: document.documentElement.style.getPropertyValue('--real-vh')
- Type: string (for example '640px')

#### Usage in CSS

- Full‑screen container: height: var(--real-vh);
- Fraction of the viewport: height: calc(var(--real-vh) * 0.5);
- Offset for headers/footers: min-height: calc(var(--real-vh) - 56px);

The value updates automatically when:

- the page loads,
- the browser window is resized,
- the orientation changes,
- the tab visibility changes (for example when switching apps),
- the visual viewport resizes or scrolls (for example when the virtual
keyboard is shown or hidden on mobile browsers that support
window.visualViewport).

$3

Importing @itrocks/real-viewport-height in a browser environment has
the following side effects:

1. Schedules an initial computation of the viewport height:
- if the document is still loading, it waits for DOMContentLoaded,
- otherwise, it runs immediately.
2. Registers event listeners on document, window, and
window.visualViewport (when available) to keep --real-vh
synchronized with the actual visible viewport.

You do not need to manage these listeners yourself; just import the
module once in your front‑end entry point.

> Note
> The internal functions and variables used to implement this behavior
> (realViewportHeight, realViewportHeightinit, and
> lastViewportHeight) are not meant to be called or modified directly
> from user code. They are considered implementation details and may
> change in future versions.

Typical use cases

- Build full‑screen layouts that behave correctly on mobile browsers
where 100vh includes the URL bar or navigation chrome.
- Ensure that main app containers, login screens, and dialogs always fit
the visible viewport, even when the on‑screen keyboard is visible.
- Avoid content being cut off or overflowing behind the browser’s UI by
basing heights and min‑heights on --real-vh instead of 100vh.
- Implement bottom sheets, drawers, or side panels sized as a fraction
of the real viewport height (for example 50%, 80%`, etc.).
- Provide a more consistent experience across devices and browsers by
centralizing viewport height handling in a single, reusable module.