package
Fast, spec-compliant CSS Object Model (CSSOM) and Typed OM parser in pure TypeScript
npm install cssomnomGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
992.3 kB
Includes dependencies.
A high-performance, zero-dependency, spec-compliant CSS Object Model (CSSOM) parser and query engine in pure TypeScript. Purpose-built for static analysis, testing, and eating style rules for breakfast.
Built with coding agents against 23,000+ W3C Web Platform Tests (WPT) across CSSOM, Syntax, Selectors, Cascade, Variables, Nesting, Media Queries, and Typed OM. Coding agents + conformance suites is a really fun meta-project (I recommend it!).
Other tools like PostCSS and CSSTree expose custom Abstract Syntax Trees (ASTs) that require learning tool-specific APIs to navigate.
cssomnom implements the standard W3C CSS Object Model (CSSOM) API. You get a familiar, standardized interface to query styles directly in Node.js. For example, you can use stylesheet.cssRules[0].style.getPropertyValue('color') instead of writing complex AST traversal code.
It is uniquely suited for static analysis and automated grading where you need to evaluate CSS rules against DOM structures without the overhead of a full browser environment.
getCascadedStyle.CSS.registerProperty(), CSSNumericValue.parse(), and complex math functions (e.g., calc, sin, atan2).cssomnom provides focused subpath entrypoints depending on what you need:
// 1. Full Package ("cssomnom"): Browser CSSOM, Typed OM, W3C CSS namespace, Cascade & Node AST tools
import { parse, getCascadedStyle, CSSNumericValue, CSS } from 'cssomnom';
// 2. Lightweight Parser & CSSOM Subset ("cssomnom/parse" — ~338 KB, >60% smaller bundle!)
// Minimal subset of "cssomnom" excluding Cascade, UA Stylesheet, and Typed OM; ideal for DOM shims (LinkeDOM) and workers
import { parse, CSSStyleSheet, CSSStyleDeclaration } from 'cssomnom/parse';
// 3. WICG CSS Parser API Draft ("cssomnom/parser-api")
import { parseStylesheet, parseRule, CSSParserAtRule, CSSParserQualifiedRule } from 'cssomnom/parser-api';Parse CSS into a standard CSSStyleSheet and traverse rules like CSSStyleRule, CSSMediaRule, and CSSNestedDeclarations.
import { parse, type CSSStyleRule, type CSSMediaRule } from 'cssomnom';
const css = `
body { color: red; }
@media (max-width: 600px) {
body {
color: blue;
margin: 0;
}
}
`;
const stylesheet = parse(css);
// Access a basic style rule
const bodyRule = stylesheet.cssRules[0] as CSSStyleRule;
console.log(bodyRule.style.getPropertyValue('color')); // 'red'
// Access nested rules (like inside an @media block)
const mediaRule = stylesheet.cssRules[1] as CSSMediaRule;
const nestedBodyRule = mediaRule.cssRules[0] as CSSStyleRule;
console.log(nestedBodyRule.style.getPropertyValue('margin')); // '0'getRules, closestRule, resolveSelector, parseSelectorAST, getDeclaredProperties, getPropertyValues)Use getRules, closestRule, resolveSelector, parseSelectorAST, getDeclaredProperties, and getPropertyValues to inspect stylesheets using standard CSSOM instances without custom wrapper objects or hand-rolled recursive visitors:
import {
parse,
getRules,
closestRule,
resolveSelector,
parseSelectorAST,
getDeclaredProperties,
getPropertyValues,
CSSStyleRule,
CSSMediaRule,
} from 'cssomnom';
const css = `
.card {
border: 1px solid var(--accent);
margin-inline-start: 1rem;
grid-template-rows: auto;
grid-template-rows: subgrid;
@media (min-width: 600px) {
color: blue;
& .title { font-weight: bold; }
}
}
@supports (interpolate-size: allow-keywords) {
:root { interpolate-size: allow-keywords; }
}
`;
const sheet = parse(css);
// 1. Collect all CSSStyleRule instances (or omit the filter class to get all CSSRule instances)
for (const rule of getRules(sheet, CSSStyleRule)) {
console.log({
rawSelector: rule.selectorText, // '.card', '& .title', ':root'
resolvedSelector: resolveSelector(rule), // '.card', ':is(.card) .title', ':root'
selectorAST: parseSelectorAST(rule), // Selectors Level 4 SelectorList AST (with '&' resolved)
media: closestRule(rule, CSSMediaRule)?.conditionText ?? null, // null, '(min-width: 600px)', null
line: rule.location?.line, // 1-based line number
rows: getPropertyValues(rule, 'grid-template-rows'), // ['auto', 'subgrid'] (preserves fallback order!)
marginLeft: getPropertyValues(rule, 'margin-left'), // ['1rem'] (resolves logical↔physical aliases!)
borderColor: getPropertyValues(rule, 'border-color'), // ['1px solid var(--accent)'] (inspects var() shorthands!)
});
}
// 2. Collect every declared property across the stylesheet (longhands, parent shorthands, and @supports features)
const props = getDeclaredProperties(sheet);
console.log(props.has('border')); // true (parent shorthand indexed alongside border-top-width, etc.)
console.log(props.has('border-color')); // true
console.log(props.has('interpolate-size')); // true (from both style rules and @supports conditions)Parse and manipulate CSS values directly as objects instead of strings using the CSS Typed OM API.
import { CSSNumericValue, CSSUnitValue, CSS } from 'cssomnom';
// Parse values
const length = CSSNumericValue.parse('10px');
console.log(length instanceof CSSUnitValue); // true
console.log(length.value); // 10
console.log(length.unit); // 'px'
// Use factory methods
const width = CSS.px(100);
const padding = CSS.rem(2);
// Complex mathematical operations
const calcValue = CSSNumericValue.parse('calc(1in + 96px)');
console.log(calcValue.toString()); // '192px' (canonicalizes to px)
const angle = CSSNumericValue.parse('calc(45deg + 0.25turn)');
console.log(angle.toString()); // '135deg'
// Note: Complex math functions (trigonometric, exponential, stepped) remain as
// tree-structured CSSMathValue objects in the Typed OM specified style rather
// than collapsing to a single scalar, preserving the calculation tree for
// computed-value time resolution per css-values-4 #calc-internal.Register custom properties with syntax validation and evaluate support for features.
import { CSS } from 'cssomnom';
// Register custom properties with syntax validation
CSS.registerProperty({
name: '--main-color',
syntax: '<color>',
inherits: false,
initialValue: 'red'
});
// Check feature support
if (CSS.supports('display', 'grid')) {
console.log('Grid is supported!');
}
if (CSS.supports('(transform-origin: 5% 5%)')) {
console.log('Conditional supports rule allowed');
}Compute the cascaded style for a particular element. You can pair cssomnom with lightweight DOM implementations like linkedom to resolve styles against HTML.
import { parse, getCascadedStyle } from 'cssomnom';
import { parseHTML } from 'linkedom';
const html = `
<div class="box highlight">Hello World</div>
`;
const css = `
.box { color: red; }
.box.highlight { color: blue; }
`;
const { document } = parseHTML(html);
const element = document.querySelector('.box');
const stylesheet = parse(css);
const style = getCascadedStyle(element, stylesheet);
const mobileStyle = getCascadedStyle(element, stylesheet, { width: 480 });
console.log(style.getPropertyValue('color')); // 'blue'For performance-critical tasks, skip the high-level object model and work directly with tokens.
import { tokenize, serialize, StreamingTokenizer } from 'cssomnom';
const cssText = '.btn { color: #fff; }';
// 1. Direct Tokenization
const tokens = tokenize(cssText);
console.log(tokens.length); // Outputs total number of tokens
// 2. Serialization (back to string)
const output = serialize(tokens);
console.log(output === cssText); // true
// 3. Streaming Tokenization (Memory Efficient)
const tokenizer = new StreamingTokenizer();
tokenizer.appendChunk('.btn { col');
tokenizer.appendChunk('or: #fff; }');
const streamingTokens = tokenizer.getTokens();
console.log(streamingTokens);This library implements standard W3C CSSOM interfaces (refer to MDN Web Docs on CSSOM).
Below are the primary entry points and custom utilities:
parse(css: string, options?: ParserOptions): CSSStyleSheet — Parses a CSS string directly into a CSSStyleSheet.tokenize(css: string): Token[] — Synchronous low-level tokenizer.serialize(nodes: ComponentValue[] | Token[]): string — Serializes component values or tokens back to CSS text.new StreamingTokenizer() — Class for processing chunked CSS streams.getRules(root, RuleClass?) — Recursively collects rules in depth-first pre-order across a CSSStyleSheet, CSSRule, or Iterable<CSSRule>, optionally narrowed to instances of RuleClass (e.g. getRules(sheet, CSSStyleRule)).closestRule(rule, ...RuleClasses) — Walks strict ancestors via rule.parentRule and returns the nearest enclosing rule matching any of RuleClasses (e.g. closestRule(rule, CSSMediaRule)).resolveSelector(rule) — Resolves CSS Nesting & combinators and relative selectors across enclosing CSSStyleRule and @scope ancestors into a canonical selector string.parseSelectorAST(input, options?) — Parses a selector string or CSSRule into a Selectors Level 4 SelectorList AST (resolving nested & selectors by default when given a CSSRule).getDeclaredProperties(root, options?) — Collects all declared CSS property names across the rule tree, including parent shorthands and @supports feature queries.getPropertyValues(target, property, options?) — Returns all authored values for property in declaration order on a CSSRule or CSSStyleDeclaration, resolving logical↔physical property aliases, unexpanded var() shorthands, and same-rule progressive-enhancement fallbacks.calculateSpecificity(selector: string | SelectorList) — Calculates selector specificity tuple [a, b, c].getCascadedStyle(element, rulesOrSheet?, pseudoOrEnv?, envOptions?) — Computes cascaded styles against a DOM/linkedom element (accepting a CSSStyleSheet or rule list, plus optional Partial<MediaEnvironment> overrides).resolveVariables(style: CSSStyleDeclaration, property: string, envMap?) — Resolves var() and env() substitutions on a CSSStyleDeclaration.This section outlines the boundaries between standard CSSOM specifications (src/entry/spec.ts) and standalone Node tooling (src/entry/tools.ts).
src/entry/spec.ts)These APIs are defined in the CSSOM-1 specification and related module extensions (CSS Conditional Rules, CSS Nesting, CSS Anchor Positioning, CSS Fonts, CSS Animations, CSS Paged Media, CSS View Transitions, and CSS Cascade). They are designed to mirror standard browser CSSOM APIs in Node.js and headless environments, and are verified bidirectionally against W3C WebIDL definitions via webidl2.js in tests/api-surface.test.ts.
Interfaces & Classes
StyleSheet, CSSStyleSheet, StyleSheetList, CSSRule, CSSRuleList, CSSGroupingRule, MediaList, LinkStyle (TypeScript interface)CSSStyleRule, CSSNestedDeclarationsCSSConditionRule, CSSMediaRule, CSSSupportsRule, CSSContainerRule, CSSLayerBlockRule, CSSLayerStatementRule, CSSScopeRule, CSSStartingStyleRuleCSSFontFaceRule, CSSPageRule, CSSPositionTryRule, CSSMarginRule, CSSKeyframesRule, CSSKeyframeRule, CSSNamespaceRule, CSSImportRule, CSSPropertyRule, CSSCounterStyleRule, CSSFontFeatureValuesRule, CSSViewTransitionRule, CSSCustomMediaRuleCSSStyleDeclaration, CSSStyleProperties, CSSFontFaceDescriptors, CSSPageDescriptors, CSSPositionTryDescriptors, CSSMarginDescriptors, CSSFontFeatureValuesMapDeviations & Extensions
insertRule() or stylesheet parsing. CSSStyleSheet supports standard CSSStyleSheetInit options (new CSSStyleSheet({ baseURL, media, disabled })).CSSStyleSheet.prototype.replace(): While the CSSOM-1 specification specifies parallel parsing for replace(), our implementation executes parsing synchronously via replaceSync() and returns Promise.resolve(this).CSSImportRule.styleSheet: Evaluates to null because the library operates as a static, offline parser without network or disk I/O to load external stylesheets.CSSRule.prototype.location): Parsed CSS rules expose their source offsets ({ start: number, end: number, line: number, column: number, bodyStart?: number, bodyEnd?: number }) relative to the original source text via a non-enumerable location property on CSSRule.prototype (with 1-based line and column numbers), enabling source maps, DevTools coverage pruning, and refactoring tools without breaking standard IDL enumeration or serialization.CSSRule.type Constants: Numeric type constants (STYLE_RULE = 1, MEDIA_RULE = 4, etc.) are retained on CSSRule instances and static constructors for backward compatibility, with modern rule types evaluating to 0.CSSStyleDeclaration supports a (parentRule?, onChange?) constructor signature and public onChange callback hook (temporarily setting decl.onChange = null suppresses callbacks when hydrating from host DOM style attributes). It also provides a full Proxy supporting camelCase (style.fontSize), kebab-case (style['font-size']), style.cssFloat, webkit* prefixes, exact case preservation on --customProperties, and WebIDL-compliant Object.keys(style) returning only indexed property names 0..length-1.CSSSupportsRule.prototype.matches returns a boolean evaluating the condition text via the conditional rules engine per CSS Conditional 4/5.CSSRule): The public Rule type is an alias for CSSRule. Custom at-rules parsed via the atRules option with parse() produce CSSAtRule instances (exported in src/entry/tools.ts) exposing .declarations (for declaration blocks) or .childRules (for rule blocks) and standard .cssText.These APIs expose low-level parsing, property registration, and typed values defined in Houdini and CSS Values specifications.
Specifications Followed
submodules/css-houdini-drafts/css-typed-om/Overview.bssubmodules/css-houdini-drafts/css-typed-om-2/Overview.bssubmodules/css-houdini-drafts/css-properties-values-api/Overview.bscssomnom/parser-api): Based on the WICG CSS Parser API draft.submodules/csswg-drafts/css-values-4/Overview.bs (Calculation trees, math functions, color models).Interfaces & Methods
import { ... } from 'cssomnom/parser-api'):
parseStylesheet(), parseRuleList(), parseRule(), parseDeclarationList(), parseDeclaration(), parseComponentValue(), parseValue(), parseValueList(), parseCommaValueList()CSSParserValue, CSSParserToken, CSSParserBlock, CSSParserFunction, CSSParserRule, CSSParserAtRule, CSSParserQualifiedRule, CSSParserDeclarationimport { ... } from 'cssomnom'):
CSSStyleValue (base class, CSSStyleValue.parse(), CSSStyleValue.parseAll())CSSKeywordValue, CSSUnparsedValue, CSSVariableReferenceValue, CSSPositionValue, CSSImageValue, CSSNumericArrayCSSNumericValue, CSSUnitValue, CSSMathValueCSSMathSum, CSSMathProduct, CSSMathNegate, CSSMathInvert, CSSMathMin, CSSMathMax, CSSMathClamp, CSSMathRound, CSSMathFunctionCSS (CSS.px(), CSS.em(), CSS.rem(), CSS.deg(), CSS.s(), CSS.Hz(), CSS.kHz(), CSS.Q(), etc.)CSSColorValue (base class)CSSColor, CSSRGB, CSSHSL, CSSHWB, CSSLab, CSSLCH, CSSOKLab, CSSOKLCHCSSTransformValue, CSSTransformComponentCSSTranslate, CSSRotate, CSSScale, CSSSkew, CSSSkewX, CSSSkewY, CSSPerspective, CSSMatrixComponentDOMMatrix, DOMMatrixReadOnlyStylePropertyMap, StylePropertyMapReadOnlyCSS):
CSS.registerProperty() (CSS Properties and Values API)CSS.supports() (CSS Conditional Rules Level 3 & 4)CSS.escape() (CSSOM Level 1)Deviations & Extensions
CSSToken as typedef (DOMString or CSSStyleValue or CSSParserValue) CSSToken;. We box raw strings in CSSParserToken instead of using raw string primitives.parseRule, parseDeclarationList, parseDeclaration, parseComponentValue, parseValue, parseValueList, and parseCommaValueList execute synchronously; parseStylesheet and parseRuleList accept strings or ReadableStreams and return a Promise.prelude, body, args) are mutable TypeScript arrays rather than FrozenArray.body is mandatory in CSSParserQualifiedRule constructor (constructor(prelude, body)).CSSMathFunction): New math functions (sin(), cos(), abs(), etc.) are represented by CSSMathFunction. Its operator getter returns the function's identifier name (e.g. 'sin').CSS.registerProperty() are enforced natively in JavaScript.CSSTransformComponent Inheritance: CSSTransformComponent inherits from CSSStyleValue, aligning with browser implementations (Blink, WebKit) and enabling reification from CSSStyleValue.parseAll() and StylePropertyMap.get().CSSNumericValue.parse() and StylePropertyMap preserve CSSMathValue tree structures per css-values-4 #calc-internal rather than performing eager unit reduction at parse time.css-typed-om #reify-property, W3C Houdini Issue #689, and WPT conformance tests, color properties accessed via StylePropertyMap (styleMap.get('color'), etc.) reify as generic base CSSStyleValue objects (with currentcolor and grammar keywords like auto on caret-color reifying as CSSKeywordValue). CSSColorValue subclasses (CSSRGB, CSSHSL, etc.) are exposed via CSSColorValue.parse(), deferring property-level color reification to Level 2 in alignment with browser engines.src/entry/tools.ts)These standalone tree-shakeable functions and classes are exported from cssomnom (src/entry/tools.ts):
Functions & Classes
parse(css, options?): Direct parser returning a constructable CSSStyleSheet (cssomnom and cssomnom/parse).getRules(root, RuleClass?): Depth-first pre-order collector returning CSSRule[] (or narrowed T[] when RuleClass is passed).closestRule(rule, RuleClass): Walks strict rule.parentRule ancestors to find the nearest enclosing RuleClass instance.resolveSelector(rule): Resolves CSS Nesting & combinators and relative selectors across enclosing CSSStyleRule and @scope ancestors into a canonical selector string.parseSelectorAST(input, options?): Parses a selector string or CSSRule into a Selectors Level 4 SelectorList AST.getDeclaredProperties(root, options?): Collects a Set<string> of all declared CSS property names across the stylesheet, including parent shorthands (border, border-color, outline, overflow, padding, margin, line-clamp, etc.) and @supports feature queries ({ includeSupports?: boolean }, default true).getPropertyValues(target, property, options?): Returns all authored values for property in declaration order on a CSSRule or CSSStyleDeclaration, resolving logical↔physical property aliases, unexpanded var() shorthands, and same-rule progressive-enhancement fallbacks.calculateSpecificity(selector): Calculates selector specificity tuple [a, b, c].tokenize(text): Low-level tokenizer returning Token[].serialize(nodes): Low-level serializer turning component values or tokens into CSS text.getCascadedStyle(element, rulesOrSheet?, pseudoOrEnv?, envOptions?): Computes cascaded styles against a DOM element.resolveVariables(style, property, envMap?): Resolves var() and env() substitutions with fallback handling.matches(element, selector) / querySelector(root, selector) / querySelectorAll(root, selector): Static selector matchers and DOM query utilities (featuring a 1,000-entry bounded LRU selector AST cache and RFC 4647 :lang() extended language range matching).StreamingTokenizer: Memory-efficient streaming generator tokenizer.CSSAtRule: Custom at-rule representation created when ParserOptions.atRules is passed to parse().API Surface Verification The public API surface area is locked down and verified by api-surface.test.ts. Any additions or removals of public exports must be reflected in that test to ensure intentional API changes.
ParseHooksThe core parser (src/parser.ts) exports standalone pure functions (parseStyleAttribute, consumeRule, consumeListOfRules, parseComponentValues, parseSelectorAST, validateCustomPropertyValue) for direct, tree-shakeable consumption by CSSOM and Typed OM modules. For upward extensibility without circular imports, ParseHooks (src/parse-hooks.ts) provides optional feature hooks (such as createStylePropertyMap, supports, and media query parsing/serialization) that higher-level modules register at bootstrap.
getComputedStyle() Support: We intentionally do not implement or expose window.getComputedStyle(). Resolving true computed styles requires a full visual rendering and layout engine (calculating font metrics, line heights, box-model geometry, viewport dimensions, and interaction states like :hover / :focus). In a server-side, headless Node.js environment, a partially correct getComputedStyle() produces subtle, misleading bugs and false confidence ("if it cannot be completely correct, partially correct is harmful"). Instead, cssomnom provides getCascadedStyle(element, rules) to resolve deterministic, declarative cascade and specificity order, leaving visual layout to real browsers.Guidelines for Maintainers
cssomnom is evaluated against the official W3C Web Platform Tests (WPT) in pure Node.js across 8 major specification suites (CSSOM, Syntax, Nesting, Variables, Selectors, Media Queries, Cascade, and Typed OM).
wpt.fyi runs.| Specification Suite | In-Scope Tests | cssomnom | Pass Rate | Parity vs Chrome 154 |
|---|---|---|---|---|
Typed OM | 12,768 | 12,224 | 95.7% | 🟢 +2.2% (ahead of Chrome) |
CSSOM | 2,527 | 2,347 | 92.9% | -4.3% |
Nesting | 126 | 126 | 100.0% | 🟢 +0.7% (ahead of Chrome) |
Syntax | 418 | 412 | 98.6% | 🟢 +0.2% (ahead of Chrome) |
Cascade | 556 | 528 | 95.0% | -4.9% |
Variables | 501 | 466 | 93.0% | 🟢 +2.5% (ahead of Chrome) |
Selectors | 5,842 | 5,178 | 88.6% | 🟢 +2.7% (ahead of Chrome) |
Media Queries | 419 | 410 | 97.9% | -0.7% |
| OVERALL | 23,157 | 21,691 | 93.7% | 🟢 +0.6% |
See wpt-progress.md for the live historical progress log and scripts/wpt/node/README.md for feasibility architecture and capability boundaries.
Run type checking:
pnpm run typecheckRun tests:
pnpm testARCHITECTURE.md: High-level codebase architecture, module ownership, and orientation map.PLAN.md: High-level project plan and roadmap (older completed phases in PLAN.archive.md).AGENTS.md: Instructions and context for AI agents working on this repo.LOOP.md: Details the multi-agent PR lifecycle loops.