chem-units

A lightweight JavaScript library for converting units commonly used in chemistry — mass, volume, pressure, energy, temperature, molarity, and 60+ other categories.

Features

• 🔋 Zero runtime dependencies in the core. The opt-in engine entry has one optional peer dependency — never loaded unless you import it.
• 📦 Dual bundle: ESM (.js) and UMD/CommonJS (.cjs), plus the separate engine entry.
• 🧪 Science focused: amount of substance, molarity, mass, length, volume, pressure, energy, temperature, conductivity, tensile force/stress, and more.
• 🏗️ Built with Vite, tested with Vitest (100% coverage).

Installation

Install using npm:

npm install chem-units

Or using yarn:

yarn add chem-units

Require Node.js >= 22.0.0.

Quick start

import { convert } from 'chem-units';

convert('pressure', 1, 'atm', 'pa'); // 101325
convert('volumes', 1, 'l', 'ml'); // 1000
convert('temperature', 0, 'C', 'F'); // 32

What it can do

Convert between units

convert(category, value, from, to, precision = 5);

Explicit source and target — the go-to function for most use cases.

convert('amount_substance', 42, 'mol', 'mmol'); // 42000
convert('mass', 1, 'g', 'mg'); // 1000
convert('length', 10, 'mm', 'cm'); // 1

Step to a unit from context

unitConversion(category, targetUnit, value, options, precision);

A simplified form for sequential stepping through a category's unit list — the source unit is inferred as whichever one precedes the target, and the conversion is skipped if the two aren't in a compatible unit family.

import { unitConversion } from 'chem-units';

unitConversion('mass', 'mg', 1); // 1000

Look up what's available

import { genUnits, genUnit, genUnitsSystem, reUnit } from 'chem-units';

genUnits('pressure'); // list of units in the pressure category
genUnit('pressure', 'atm'); // a single unit's definition
genUnitsSystem(); // the full unit system (all categories)
reUnit('pressure'); // the category's default/representative unit

See the Supported Units wiki page for the complete list of categories and unit keys.

Other exports

| Export | Purpose | | :--- | :--- | | convert(category, value, from, to, precision) | Convert a value between two explicit units. | | convertTemperature(key, value) | Temperature conversion (Celsius pivot — not nm-based, since temperature scales aren't linear ratios). | | genUnit(category, key) | A single unit's definition. | | genUnits(category) | List of units in a category. | | genUnitsSystem(options) | The full unit system (all categories). | | getVersion() | Library version. | | reUnit(category) | A category's default/representative unit. | | unitConversion(category, targetUnit, value, options, precision) | Convert by stepping to a unit from the one before it in the category's list. |

Unit-aware arithmetic

For formulas that combine values across units — e.g. mg/L × L → mg — the engine entry gives you unit-aware values you can build, combine, and convert back.

Install the peer dependency alongside the library:

yarn add chem-units mathjs

import { toEngineUnit, convertToKey, isAffineUnit } from 'chem-units/engine';

const u = toEngineUnit(5, 'mg_l'); // engine unit: 5 mg/L
convertToKey(u, 'g_l'); // 0.005
convertToKey(0.5, 'p'); // 50 — dimensionless result shown as %
isAffineUnit('C'); // true — offset unit; arithmetic on it is ambiguous

| Export | Returns | Purpose | | :--- | :--- | :--- | | convertToKey(unitOrNumber, key) | number | null | Express an engine result in a key's unit; scales dimensionless results for %/ppm/ppb-style keys. | | getDimensionlessScale(key) | number | null | Display scale for dimensionless keys: p/wt_p/vol_p → 100, ppm → 1e6, ppb → 1e9. | | getEngineUnit(key) | string | null | Raw key-to-engine-expression lookup (also available from the main entry). | | isAffineUnit(key) | boolean | true for offset temperatures (C, F) — their conversions are fine, but arithmetic on them is ambiguous since magnitudes get added directly, ignoring offsets. Rate keys like degc_min are multiplicative and stay false. | | toEngineUnit(value, key) | Unit | null | Build an engine unit from a unit key (null if unmapped/dimensionless). |

All lookups are null-safe — unmapped keys, dimension mismatches, and unknown keys return null (or false) instead of throwing.

Development

yarn install
yarn dev          # interactive playground — pick a category, convert live, hot-reloaded from source
yarn build         # build dist/: main ESM + UMD, and the engine entry (ESM + CJS, peer dependency external)
yarn test          # build, run Vitest with coverage, then validate the packaged imports
yarn test:unit     # just the Vitest suite, no rebuild
yarn lint          # eslint . (or lint:fix)

Contributing

Bug reports, missing units, and pull requests are welcome on GitHub. For specific inquiries, contact the maintainer Chia-Lin Lin.

Acknowledgments

Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under the National Research Data Infrastructure – NFDI4Chem – Projektnummer 441958208.