fp-units

An FP-oriented library to easily convert CSS units. Provides some convenient curried functions to convert any CSS units available in the spec.

Installation
Basic usage
Supported units
API

Installation

npm install --save fp-units

Basic usage

Absolute units

import { converter } from 'fp-units'

converter({}, 'px', '100px 2cm 15mm 4q 4in 30pc 24pt')
// [[100, 75.59055, 56.69291, 3.77953, 384, 480, 32]]

converter({}, 'px', [30, '4px 8px', '2cm'])
// [[30], [4, 8], [75.59055]]

converter({}, 'px', 30)
// [[30]]

converter({}, 'px', 'calc(2 * calc(12px + 3px))')
// [[30]]

Relative units

In order to be able to do conversions between relative units, fp-units needs to know some values to perform calculus. For example, to convert px into %, you have to provide a fixed size to let fp-units know on what constant coefficient it should base the converter.

In a browser environment, fp-units is able to guess the majority of the configuration object by itself: in most cases, you'll just have to provide the node property. For more advanced config, please see the config object below.

import { converter } from 'fp-units'

converter(
  { node: document.querySelector('#foobar') },
  'px',
  '2rem 4em 2rlh 4lh 50% 25vw 40vh 5vmin 10vmax',
)
// [[32, 96, 32, 104, 50, 480, 432, 54, 192]]

Note: since all the provided functions are automatically curried, you can create a custom to function based on your own configuration:

import { converter } from 'fp-units'

const to = converter({ /* your config */ })

to('px', '5rem')
to('%', '30vw')
to('vmin', '50% 40px')

Config object

All properties are optional.

const config = {
  // used to convert vw, vh, vmin, vmax
  window: window,
  // fallback
  window: {
    innerWidth: 0,
    innerHeight: 0,
  },

  // used to convert rem, rlh
  document: document,
  // fallback
  document: {
    lineHeight: 16,
    fontSize: 16,
  },

  // used to convert em, lh, %
  node: document.querySelector('#foobar'),
  // fallback
  node: {
    lineHeight: 16,
    fontSize: 16,
    width: 0, // must match `property` below
  },

  // specify the style property to look for in `node`
  // used to convert %
  property: 'width',
}

Supported units

fp-units supports conversions of every units described in the CSS spec, as long as the starting unit and the arrival unit have the same nature. For example, it is possible to convert px to %, but it is impossible to convert deg to px, because deg describes an angle while px describes a length.

Length

px (canonical), cm, mm, q, in, pt, pc, %, em, rem, ex, ch, ic, lh, rlh, vw, vh, vmin, vmax, vb, vi

Angle

rad (canonical), deg, grad, turn

Time

s (canonical), ms

Frequency

hz (canonical), khz

Resolution

dppx (canonical), dpi, dpcm

API

convert

Naively converts a numeric value into the desired unit. This function is more granular than converter, but it does not handle automatic parsing, calc expressions and multiple conversions. This function is more useful when you need specialized converters.

The config object allows you to adjust some parameters used to perform relative units conversions (e.g. rem or %).

Parameters

config Object The config object.
unit string The desired unit.
from string The base unit.
value number The value to convert.

Examples

import { convert } from 'fp-units'

convert({}, 'rem', 'px', 32)
// 2

convert({}, 'deg', 'rad', Math.PI)
// 180

// Note: you can take advantage of automatic currying to have your own conversion API!
const rad2deg = convert({}, 'deg', 'rad')

rad2deg(Math.PI)
// 180

rad2deg(Math.PI / 4)
// 45

Returns number

converter

Smartly converts the provided values into the desired unit. You can convert numbers, strings and calc expressions.

Note: if the provided values don't have any unit, it will assume that they are expressed in the canonical unit corresponding to the nature of the desired unit (e.g. px if the desired unit is a length).