Introducing css-typed-om, a complete and WPT-tested polyfill for CSS Typed OM

~

# Why CSS Typed OM? (And why a polyfill?)

If you’ve ever read or manipulated styles in JavaScript using element.style or window.getComputedStyle(), you know the pain of dealing with strings. Want to read an element’s width and add 20px to it? You have to parse the string, strip the unit, convert it to a number, do the math, and concatenate it back into a string. Throw calc(), transform matrices, or modern color spaces into the mix, and string manipulation quickly falls apart.

const styles = getComputedStyle($el);
const opacity = styles.getPropertyValue('opacity');

console.log(opacity); // '0.2'
console.log(typeof opacity); // String!?

That’s where the CSS Typed Object Model (CSS Typed OM) comes in. Instead of strings, it exposes CSS values as typed JavaScript objects — such as CSSUnitValue, CSSMathSum, CSSTransformValue, and CSSKeywordValue — through element.attributeStyleMap, element.computedStyleMap(), and unit factory functions like CSS.px(20).

const styles = $el.computedStyleMap();
const opacity = styles.get('opacity');

console.log(opacity); // CSSUnitValue
console.log(opacity.value); // 0.2
console.log(opacity.unit); // 'number

However, browser support isn’t 100% uniform yet. While Chromium and Safari ship CSS Typed OM, Firefox’s native implementation is still a work in progress behind the layout.css.typed-om.enabled flag (see Firefox bug 1278697). And even in browsers that do support Typed OM, some newer parts of the spec — like the CSSColorValue subclasses (CSSRGB, CSSOKLCH, etc.) — aren’t available everywhere yet.

~

# Enter css-typed-om

Building a standalone CSS Typed OM polyfill has been sitting on my backlog for years — especially when seeing other projects like the (partial) scroll-timeline polyfill having to roll and bundle parts of the CSS Typed OM implementation themselves just to support unit values like CSS.percent() or CSS.px().

However, the CSS Typed OM specification is huge, covering everything from a full CSS tokenizer and calc() expression simplifier to 2D/3D matrix math and WebIDL interface rules. Writing all of that by hand was simply too big of an undertaking for a side project. But now, thanks to AI, that long-standing goal finally came within reach: meet css-typed-om. Guided by the specification and the official Web Platform Tests, css-typed-om is a complete, standalone, and full tested polyfill that you can drop into any project. 🚀

~

# Installation & Usage

You can install the package from npm:

npm install css-typed-om

Depending on your setup, you can use css-typed-om in two ways.

~

1. As a Global Polyfill

Import the package once at the entry point of your application to automatically patch window.CSS, Element.prototype.computedStyleMap, HTMLElement.prototype.attributeStyleMap, and all CSS Typed OM classes:

import 'css-typed-om';

// Read computed styles as typed objects
const element = document.querySelector('.my-element');
const width = element.computedStyleMap().get('width');

console.log(width.value); // e.g., 100
console.log(width.unit);  // e.g., 'px'

// Set inline styles using CSS unit factories
element.attributeStyleMap.set('opacity', CSS.number(0.5));
element.attributeStyleMap.set('margin-top', CSS.px(20).add(CSS.em(2)));

~

2. As an Explicit ES Module

If you prefer importing the classes directly (for example in unit tests or modular libraries):

import { CSSUnitValue, CSSKeywordValue } from 'css-typed-om';

const width = new CSSUnitValue(100, 'px');
const display = new CSSKeywordValue('block');

~

# Tested against Web Platform Tests (WPT)

When building a polyfill for a spec as sprawling as CSS Typed OM, custom unit tests alone aren’t enough. There are hundreds of edge cases around calc() simplification, serialization order, out-of-range value clamping, shorthand properties, and WebIDL interface rules.

To make sure the polyfill behaves just like a native implementation, I wired the repository directly up to the official Web Platform Tests (WPT) suite. Running npm run test:wpt spins up headless Firefox (with its experimental native layout.css.typed-om.enabled flag explicitly disabled), injects the IIFE build of the polyfill, and runs all 400+ WPT test files in /css/css-typed-om/.

At the time of writing, the polyfill passes 12,479 out of 13,134 WPT subtests (~95%)! 🙂

~

# Acknowledgements & Links

First of all, a shout-out to Johannes Odland, who had PR’d some significant CSS Typed OM parts into the scroll-timeline polyfill back in the day. It’s his work that first sparked the idea of writing a full, standalone CSS Typed OM polyfill.

A special shout-out and thank you goes to Jonathan Neal, who kindly handed over the css-typed-om package name on npm (which previously housed the now-archived csstools/css-typed-om project). Thanks, Jonathan! 🙌

• css-typed-om on GitHub →
• css-typed-om on npm →

~

# Spread the word

Feel free to reshare one of the following posts on social media to help spread the word:

• 🦋 Bluesky
• 🦣 Mastodon
• 💼 LinkedIn

~