alexdunphy/units

Got units? Convert them! Parse length, angle and resolution CSS values and convert between units.

Units

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

Install

Bower: bower install -S units-css

npm: npm i -S units-css

(One object is exported:)

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

API

#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': ''}

Transforms

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

Element

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

Property

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%

Transforms

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

#getDefaultValue(property)

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

#getDefaultUnit(property)

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'

Environment

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

Development

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).

units's Issues

Incorrect conversion for vertical-align

For vertical-align, the two numeric values it can take are percentage and length.

• Length in this case is offset from text's baseline
• Percentage is offset from baseline as a percentage of line height
  So to correctly convert them you need to calculate line height. Unfortunately, getComputedStyle for line-height can return "normal" (appears to be "px" for all other cases). Perhaps a way to convert "normal" could be to measure something like:

getCreatedElementHeight(document.body, {
    lineHeight: el_styles.lineHeight, 
    fontFamily: el_styles.fontFamily, 
    fontSize: el_styles.fontSize
});

Though that may not be entirely reliable

Conversion to % does not work with position: fixed elements

When you try to convert from PX to % on an element, which is a child of body and has fixed position, it will throw an error on utilities.getRelativeElementDimension, when trying to get element.offsetParent, which is null in that case.

The solution I propose is to add document.documentElement fallback to offsetParent:
reference = positioned ? element.offsetParent || document.documentElement : element.parentNode;

Suggestion for using builtin DOM API for conversion

I recently discovered the SVG DOM API provides some builtin unit conversion functionality. It would not be applicable to all cases, but I suspect it could possibly be more reliable and faster for the cases it can be used for.

See my SO answer here

Server side rendering

The problem with server side rendering is that window doesnt exist. Neiter can it look what px the body has. Would be nice if the prop element also could be a numeric value in px.
units.convert('rem', '16px', 16);

Dependency on document.body

This library was required from a Node Canvas dependency in our app and was failing because our code was initialised in the head rather than the body, so document.body didn't exist. This was the error for anyone googling

utilities.js: Uncaught TypeError: Cannot read property 'appendChild' of null