Index / Blog / Scale all the things with postcss-px-to-viewport

Introducing postcss-px-to-viewport: open-source software to create scalable interfaces on any display

postcss-px-to-viewport is a plug-in for PostCSS that converts px values to viewport units (vw, vh, etc.)

April 2020

Most mobile and cross-platform web developers have encountered the problem at some point: you need your web app to scale neatly to the device screen size, regardless of which of the many thousands of devices there are out there, but your units only have one design layout width, mainly mobile. Or perhaps you need to create a per-device stylesheet for a truly scalable cross-platform UI, and want to use a scaled version of an original to base it upon. In either case, converting everything by hand is laborious and inconvenient.

Grappling with this problem in one of our projects, the app, our leading frontend developer Dmitriy Karpunin came up with the idea of using a post-processor to convert CSS values from one set of units to another, and that’s how postcss-px-to-viewport, a plug-in for PostCSS that converts px values to viewport units (vw, vh, etc.), was born.

For example, if you specify a notional horizontal resolution of 640 pixels and you specify a horizontal distance of 32px, the plug-in will convert that to 5vw in the output, because 32 pixels is 5% of the 640 pixel viewport width.

The plug-in also has plenty of options for customisation, to control exactly which values to convert, and where, and based upon which notional resolution.


Installation is straightforward with npm:

$ npm install postcss-px-to-viewport --save-dev

or with yarn, if you prefer:

$ yarn add -D postcss-px-to-viewport


To configure the plug-in, add a 'postcss-px-to-viewport' object to your postcss.config.js as shown below:

module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
       unitToConvert: 'px',
       viewportWidth: 320,
       unitPrecision: 5,
       propList: ['*'],
       viewportUnit: 'vw',
       fontViewportUnit: 'vw',
       selectorBlackList: [],
       minPixelValue: 1,
       mediaQuery: false,
       replace: true,
       exclude: [],
       landscape: false,
       landscapeUnit: 'vw',
       landscapeWidth: 568

The options listed above are shown with their default values, and any that you don't wish to override can be omitted.

To use postcss-px-to-viewport with gulp-postcss, add a task to your gulpfile.js along the lines of the below:

var gulp = require('gulp');
var postcss = require('gulp-postcss');
var pxtoviewport = require('postcss-px-to-viewport');
gulp.task('css', function () {
    var processors = [
            viewportWidth: 320,
            viewportUnit: 'vmin'
    return gulp.src(['build/css/**/*.css'])


Widely used across Asia

One day in Summer 2018, we discovered an active community had sprung up around the plug-in in China — suddenly, the issues, pull requests, and forks came flooding in.

Much of Asia, but China, in particular, suffers from an active proliferation of devices that developers are tasked with supporting, and postcss-px-to-viewport quickly became invaluable to many!

We quickly realised that it would be helpful if the plug-in came with instructions in Chinese, not just English, and we were thrilled when a community volunteer answered our call and contributed a Chinese-language Readme for the project.


postcss-px-to-viewport is an excellent example of a utility that does one thing and does it well, and we encourage others to open similar tools they may have written. And, if you encounter any problem in the development of your project and cannot find a ready-made solution, we are here to help you develop a plugin or even a software that will solve your problem and possibly help thousands of other developers.

Many developers are afraid to spread their knowledge via writing open-source, but there is nothing to be afraid of! You just need a tool that solves a specific problem, and the community will support and help. The development philosophy is based on mutual assistance and a desire to help each other; this is the real meaning of open-source.
Dmitriy Karpunin
Chief Frontend,
Let’s talk about you
Attach file
Files must be less than 8 MB.
Allowed file types: jpg jpeg png txt rtf pdf doc docx ppt pptx.
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.