units-css

What is units-css?

The units-css npm package provides utilities for converting and manipulating CSS units. It simplifies the process of working with different units in CSS, such as pixels, ems, rems, percentages, and more.

What are units-css's main functionalities?

Convert units

This feature allows you to convert one CSS unit to another. In the example, 16 pixels are converted to ems based on a base size of 16 pixels.

const units = require('units-css');
const pxToEm = units.convert('16px', 'em', { base: '16px' });
console.log(pxToEm); // '1em'

Parse units

This feature parses a CSS unit string into an object containing the numeric value and the unit. In the example, '16px' is parsed into an object with value 16 and unit 'px'.

const units = require('units-css');
const parsed = units.parse('16px');
console.log(parsed); // { value: 16, unit: 'px' }

Stringify units

This feature converts an object with a value and unit back into a CSS unit string. In the example, an object with value 16 and unit 'px' is converted back to '16px'.

const units = require('units-css');
const stringified = units.stringify({ value: 16, unit: 'px' });
console.log(stringified); // '16px'

Other packages similar to units-css

css-unit-converter

The css-unit-converter package provides similar functionality for converting between different CSS units. It offers a straightforward API for unit conversion but lacks some of the parsing and stringifying capabilities of units-css.

postcss-pxtorem

The postcss-pxtorem package is a PostCSS plugin that converts pixel units to rem units. While it focuses specifically on px to rem conversion, it integrates well with PostCSS workflows, unlike units-css which is a standalone utility.

css-values

The css-values package provides utilities for parsing and manipulating CSS values, including units. It offers a broader range of CSS value manipulations compared to units-css, which is more focused on unit conversions.

README

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

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