{"id":13025,"library":"cssom","title":"CSSOM Parser and Object Model","description":"CSSOM.js is a pure JavaScript CSS parser and a partial implementation of the W3C CSS Object Model (CSSOM). Currently at version 0.5.0, this library provides functionality to parse raw CSS strings into a structured object representation, allowing for basic programmatic inspection and manipulation of CSS rules. Its release cadence has been slow, with the last publish being 5 years ago. A key differentiator is its direct representation of CSS as a JavaScript object. However, it explicitly advises against its use for advanced CSS processing tasks such as minification, munging, or reformatting, particularly where the preservation of property order or fallback declarations (e.g., `background: gray; background: linear-gradient(...)`) is critical, as it applies CSS cascade rules and overwrites properties. It also has known limitations, including incomplete support for all CSS escape sequences and incompatibility with Internet Explorer versions prior to 9.","status":"maintenance","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/NV/CSSOM","tags":["javascript","CSS","CSSOM","parser","styleSheet"],"install":[{"cmd":"npm install cssom","lang":"bash","label":"npm"},{"cmd":"yarn add cssom","lang":"bash","label":"yarn"},{"cmd":"pnpm add cssom","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `cssom` package is primarily a CommonJS module for Node.js environments. For browser usage, a global `CSSOM` variable is exposed after running the `build.js` script and including the resulting file. Direct ESM imports are not officially supported.","wrong":"import CSSOM from 'cssom';","symbol":"CSSOM","correct":"const CSSOM = require('cssom');"},{"note":"The `parse` function is a method of the main `CSSOM` object, not a named export. Attempting to destructure it directly will result in an error as it's not a standalone function.","wrong":"import { parse } from 'cssom';","symbol":"parse","correct":"const CSSOM = require('cssom');\nconst parsedCSS = CSSOM.parse('body {color: black;}');"},{"note":"Like `parse`, `CSSStyleDeclaration` (and other CSSOM interfaces) are properties of the main `CSSOM` object. They are not individually exported for direct named imports.","wrong":"import { CSSStyleDeclaration } from 'cssom';","symbol":"CSSStyleDeclaration","correct":"const CSSOM = require('cssom');\nconst styleDeclaration = new CSSOM.CSSStyleDeclaration();"}],"quickstart":{"code":"const CSSOM = require('cssom');\n\nconst cssString = `\n  body {\n    font-family: Arial, sans-serif;\n    color: #333;\n  }\n  .container {\n    width: 960px;\n    margin: 0 auto;\n    padding: 20px;\n    background: #f0f0f0;\n    /* This will be overwritten */\n    background: linear-gradient(to bottom, white 0%, black 100%);\n  }\n`;\n\nconst stylesheet = CSSOM.parse(cssString);\n\nconsole.log('Parsed CSS Rules:');\nstylesheet.cssRules.forEach(rule => {\n  if (rule.selectorText) {\n    console.log(`Selector: ${rule.selectorText}`);\n    for (let i = 0; i < rule.style.length; i++) {\n      const prop = rule.style[i];\n      console.log(`  ${prop}: ${rule.style[prop]}`);\n    }\n  }\n});\n\n// Demonstrating the property overwriting issue\nconst containerRule = stylesheet.cssRules.find(r => r.selectorText === '.container');\nif (containerRule) {\n  console.log('\\nProperties for .container after parsing:');\n  // Note: Only the last 'background' property will be present due to cascading logic.\n  console.log(`  background: ${containerRule.style.background}`);\n}","lang":"javascript","description":"This quickstart demonstrates how to parse a CSS string using `CSSOM.parse()` in Node.js and iterate through the resulting CSS rules and their styles, highlighting the property overwriting behavior."},"warnings":[{"fix":"For CSS minification, munging, or reformatting where property order and all declarations must be preserved, consider using purpose-built tools like PostCSS, ReworkCSS, CSSTree, or CSSToJSON.","message":"CSSOM applies standard CSS cascade logic, which means that if multiple declarations for the same property exist within a single rule (e.g., fallback `background` values), only the last one will be preserved in the parsed output, overwriting previous declarations. This makes it unsuitable for tools requiring preservation of such fallbacks.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Preprocess CSS to normalize or resolve complex escape sequences before feeding them into CSSOM, or handle them manually in post-processing of the parsed output.","message":"The library has limited support for CSS escape sequences. While `\\'` and `\\\"` are allowed, full CSS escape sequence handling is not implemented.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Ensure that the target browser environment is IE9+ if using CSSOM on the client-side. For broader compatibility, consider alternative client-side CSS parsers or polyfills for the necessary JavaScript features.","message":"CSSOM.js does not work in Internet Explorer versions prior to IE9 due to its reliance on unsupported getters/setters in those older browsers.","severity":"gotcha","affected_versions":"<0.5.0"},{"fix":"Evaluate the long-term viability for new projects. For ongoing development or critical applications, consider modern, actively maintained alternatives like PostCSS or the browser's native CSS Typed OM (where supported).","message":"The GitHub repository README for CSSOM explicitly states that the project is 'Unmaintained!'. While the npm package is still available, active development and issue resolution are not ongoing, with the last publish being 5 years ago.","severity":"deprecated","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For Node.js, add `const CSSOM = require('cssom');` at the top of your file. For browser use, run `node build.js` in the project directory and then include the generated `build/CSSOM.js` file in your HTML using a `<script>` tag.","cause":"Attempting to use `CSSOM` in a Node.js environment without `require('cssom')`, or in a browser without including the `build/CSSOM.js` file generated by the build process.","error":"ReferenceError: CSSOM is not defined"},{"fix":"Ensure you import the entire `CSSOM` object using `const CSSOM = require('cssom');` and then call `CSSOM.parse(...)`.","cause":"This error typically occurs if you try to import `parse` as a named export (`import { parse } from 'cssom'`) or if `require('cssom')` does not return the expected `CSSOM` object. The `parse` method is a property of the main `CSSOM` object.","error":"TypeError: CSSOM.parse is not a function"},{"fix":"If your use case requires preserving all declarations, including fallbacks or duplicate properties, CSSOM is not the right tool. Consider using alternative CSS parsers like PostCSS or reworkcss/css, which offer more granular control over parsing and AST manipulation.","cause":"CSSOM's parser applies standard CSS cascading rules, which results in duplicate properties within a single rule (e.g., `background: gray; background: linear-gradient(...)`) being overwritten, with only the last valid declaration being preserved.","error":"Unexpected parsing result: CSS property values are overwritten or missing."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}