node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


Travis CI status Coveralls status dependencies status devDependencies status

Sauce Labs status


Parse length and angle CSS values and convert between units.

Supported units:

Length: %, ch, cm, em, ex, in, mm, pc, pt, px, rem, vh, vmax, vmin, vw

Angle: deg, grad, rad, turn


Bower: bower install -S units-css

npm: npm i -S units-css

(One object is exported:)

var units = require('units-css');


#parse(value, property)

Extract the numeric value and unit from a formatted CSS value:

units.parse('1px'); // {'value': 1, 'unit': 'px'} 

Or, passing only a value or only a unit:

units.parse(1);    // {'value': 1, 'unit': ''} 
units.parse('px'); // {'value': 0, 'unit': 'px'} 

Optionally pass a CSS property name as the second argument to enable property-specific defaults:

// Absent units 
units.parse(1, 'width');   // {'value': 1, 'unit': 'px'} 
units.parse(1, 'opacity'); // {'value': 1, 'unit': ''} 
units.parse(1, 'rotate');  // {'value': 1, 'unit': 'deg'} 
// Absent values 
units.parse('', 'width');   // {'value': 0, 'unit': 'px'} 
units.parse('', 'opacity'); // {'value': 1, 'unit': ''} 

transform should not be passed directly as the property name - instead specify a transform keyword (e.g. rotate).

#convert(to, value, element, property)

Convert a formatted CSS value to a different unit (see supported units). For example:

units.convert('cm', '12px'); // 0.3175 

Conversions to/from %, ch, em, ex require an element be passed as the third argument. This should be the element to which the converted CSS value applies/will apply:

units.convert('em', '16px', document.getElementById('some-element')); // 1em 

Conversions to/from % require a CSS property name (e.g. width) be passed as the fourth argument. This should be the matching property name for the converted CSS value:

units.convert('%', '16px', document.getElementById('some-element'), 'translateX'); // 10% 

transform should not be passed directly as the property name - instead specify a transform keyword (e.g. rotate).


Get a default numeric value for a CSS property:

units.getDefaultValue('opacity');    // 1 
units.getDefaultValue('scale');      // 1 
units.getDefaultValue('scale3d');    // 1 
units.getDefaultValue('scaleX');     // 1 
units.getDefaultValue('scaleY');     // 1 
units.getDefaultValue('scaleZ');     // 1 
units.getDefaultValue('lineHeight'); // 1 

All other properties will return 0, for example:

units.getDefaultValue('width'); // 0 


Get a default unit for a CSS property:

units.getDefaultUnit('opacity');    // '' 
units.getDefaultUnit('rotate');     // 'deg' 
units.getDefaultUnit('rotate3d');   // 'deg' 
units.getDefaultUnit('rotateX');    // 'deg' 
units.getDefaultUnit('rotateY');    // 'deg' 
units.getDefaultUnit('rotateZ');    // 'deg' 
units.getDefaultUnit('skew');       // 'deg' 
units.getDefaultUnit('skewX');      // 'deg' 
units.getDefaultUnit('skewY');      // 'deg' 
units.getDefaultUnit('scale');      // '' 
units.getDefaultUnit('scale3d');    // '' 
units.getDefaultUnit('scaleX');     // '' 
units.getDefaultUnit('scaleY');     // '' 
units.getDefaultUnit('scaleZ');     // '' 
units.getDefaultUnit('lineHeight'); // '' 

All other properties will return 'px', for example:

units.getDefaultUnit('width'); // 'px' 


Server-side use is supported, though converting to/from the following units requires a browser environment: %, ch, em, ex, rem, vh, vmax, vmin, vw.


  1. Clone repo and npm install
  2. Make changes and ensure linting (gulp lint) & tests (gulp test) pass (combined task: gulp dev)
  3. Create distributable files (gulp dist) - combined dev + dist task: gulp

Use gulp watch to run linter and tests on each file change (equivalent to manually running gulp dev).