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');
Or, passing only a value or only a unit:
units.parse(1);
units.parse('px');
Optionally pass a CSS property name as the second argument to enable property-specific defaults:
units.parse(1, 'width');
units.parse(1, 'opacity');
units.parse(1, 'rotate');
units.parse('', 'width');
units.parse('', 'opacity');
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');
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'));
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');
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');
units.getDefaultValue('scale');
units.getDefaultValue('scale3d');
units.getDefaultValue('scaleX');
units.getDefaultValue('scaleY');
units.getDefaultValue('scaleZ');
units.getDefaultValue('lineHeight');
All other properties will return 0
, for example:
units.getDefaultValue('width');
#getDefaultUnit(property)
Get a default unit for a CSS property:
units.getDefaultUnit('opacity');
units.getDefaultUnit('rotate');
units.getDefaultUnit('rotate3d');
units.getDefaultUnit('rotateX');
units.getDefaultUnit('rotateY');
units.getDefaultUnit('rotateZ');
units.getDefaultUnit('skew');
units.getDefaultUnit('skewX');
units.getDefaultUnit('skewY');
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');
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
- Clone repo and
npm install
- Make changes and ensure linting (
gulp lint
) & tests (gulp test
) pass (combined task: gulp dev
) - 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
).