joppuyo / large-small-dynamic-viewport-units-polyfill

Polyfill for svh, dvh and lvh CSS viewport units

Large, small, and dynamic viewport units polyfill

This is a "polyfill" which adds support for svh, dvh and lvh viewport units. It's mainly useful when dealing with iOS and Android mobile devices.

⚠️ This library is pre-release quality. It should work but it requires more comprehensive testing on different devices. Please test it out and report any bugs you might encounter.

How it works

It adds CSS custom properties (variables) --1svh, --1dvh and --1lvh using JavaScript. These correspond to 1 svh, 1 dvh and 1 lvh unit respectively. These custom properties are automatically updated when the viewport size changes. You can use CSS calc() function to multiply them to your desired size.

How to use

1. Import script

Include script tag or import the script using a bundler.

1.A. Script tag

<script src="https://unpkg.com/[email protected]/dist/large-small-dynamic-viewport-units-polyfill.min.js"></script>

1.B. Bundler

Install the package.

npm install large-small-dynamic-viewport-units-polyfill

Import the package.

import 'large-small-dynamic-viewport-units-polyfill';

2. Write CSS

Add CSS like this in your project:

.my-small-hero-element {
    width: 100%;
    height: 100vh; /* For browsers that don't support CSS variables */
    height: calc(var(--1svh, 1vh) * 100); /* This is the "polyfill" */
    height: 100svh; /* This is for future browsers that support svh, dvh and lvh viewport units */
}

.my-dynamic-hero-element {
    width: 100%;
    height: 100vh; /* For browsers that don't support CSS variables */
    height: calc(var(--1dvh, 1vh) * 100); /* This is the "polyfill" */
    height: 100dvh; /* This is for future browsers that support svh, dvh and lvh viewport units */
}

.my-large-hero-element {
    width: 100%;
    height: 100vh; /* For browsers that don't support CSS variables */
    height: calc(var(--1lvh, 1vh) * 100); /* This is the "polyfill" */
    height: 100lvh; /* This is for future browsers that support svh, dvh and lvh viewport units */
}

⚠️ You should include all three lines so your styles will work properly. Because browsers will simply ignore CSS properties with values they do not understand, new browsers that implement the units will use the last line.

You may omit the first line if you don't need to support very old browsers like IE 11 (As of 2023, CSS custom properties are supported by 97% of browsers).

ℹ️ lvh unit is only included for the sake of completeness. It currently behaves exactly like vh unit. This may break in a future version of iOS or Android.

Compatibility

I've tested this library with the following operating systems and devices:

• Mobile Safari, iOS 15, iPhone 12 Pro
• Mobile Safari, iOS 15, iPad Pro 11" 2018
• Mobile Safari, iOS 14, iPhone SE (1st generation)
• Mobile Safari, iOS 15.2, iPhone 13 Pro (Simulator)
• Mobile Safari, iOS 15.2, iPad Pro (11-inch, 3rd Generation, Simulator)
• Mobile Safari, iOS 16.1, iPhone 14 Pro (Simulator)
• Mobile Safari, iOS 16.1, iPad Pro (11-inch, 4th Generation, Simulator)
• Google Chrome 97, iOS 15, iPhone 12 Pro
• Google Chrome 97, iPadOS 15, iPad Pro 11" 2018
• Google Chrome 97, Android 8.1, Nexus 5X
• Google Chrome 108, Android Emulator

Todo

• Add some automated tests
• Figure out how to run automated tests on mobile devices (preferably on the cheap)

Further reading

• The Large, Small, and Dynamic Viewports – Bram.us
• The trick to viewport units on mobile – CSS-Tricks
• New Viewport Units Introduced to Values and Units L4 – CSS WG Blog

large-small-dynamic-viewport-units-polyfill's Issues

Supports check

Don't run on devices that support new units

GitHub actions

User GitHub action to build the library and release it to NPM

Only run on mobile devices

var isMobile = function() {
  return /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
}

lvmax, svmax, dvmax, lvmin, svmin, dvmin

Finalize API

• Decide if we want automatic, self-instantiating API or an explicit function that needs to be run by the user (check how some other popular polyfills work)
• Provide an API so the user can refresh the css properties on demand
• Figure out CommonJS, AMD, RequireJS, ES6 Modules and UMD stuff
• Provide a way to use the library with script tag (attach a global to the window object)

Throttle/debounce event listener

We should probably throttle/debounce the resize event listener to improve performance