Why Migrate?

CSS Parser has served the Java community well for many years. However, it is built on top of the SAC (Simple API for CSS) interface (org.w3c.css.sac), whose last release — version 1.3 — dates back to 2008. The W3C itself describes SAC as a draft that may be “updated, replaced or obsoleted.”

As CSS evolved with new selectors (:is(), :has(), :where()), modern color functions (hwb(), oklch()), viewport units (dvw, svh), and more, the rigid SAC API made it impossible to represent these new constructs properly. This is the primary reason HtmlUnit-CSSParser was created: by removing the SAC dependency, the parser gained the flexibility to keep pace with modern CSS.

HtmlUnit-CSSParser started as a fork of CSS Parser 0.9.25 and has since grown significantly. It is the CSS parser powering HtmlUnit since version 1.30.

Feature Comparison

CSS Parser (this project) HtmlUnit-CSSParser
Latest Version 0.9.30 (Dec 2022) 4.21.0 (Dec 2025)
SAC Dependency Required (stalled since 2008) Removed
CSS Level 3+ Support Partial — limited by SAC Extensive, including CSS4 selectors
Modern Selectors — :is(), :has(), :where() with correct specificity
Modern Color Functions — hwb(), lab(), lch(), oklab(), oklch(), relative colors
Viewport Units — dvw, dvh, dvmin, dvmax, lvw, lvh, lvmin, lvmax, svw, svh, svmin, svmax
var() / calc() in colors — Supported
Java Requirement JDK 1.8+ JDK 8+ (v4.x) / JDK 17+ (v5.x)
Distribution SourceForge / Maven Central Maven Central
Source Code SourceForge GitHub
License Apache 2.0 Apache 2.0 (unchanged)

Migration Steps

Step 1: Replace the Dependency

Remove the old CSS Parser dependency from your build file:

<!-- Remove -->
<dependency>
    <groupId>net.sourceforge.cssparser</groupId>
    <artifactId>cssparser</artifactId>
    <version>0.9.30</version>
</dependency>

Add the HtmlUnit-CSSParser dependency:

<!-- Add -->
<dependency>
    <groupId>org.htmlunit</groupId>
    <artifactId>htmlunit-cssparser</artifactId>
    <version>4.21.0</version>
</dependency>

Or for Gradle:

implementation 'org.htmlunit:htmlunit-cssparser:4.21.0'

Step 2: Update Import Statements

The main package has changed. Update your imports:

Old (CSS Parser) New (HtmlUnit-CSSParser)
com.steadystate.css.* org.htmlunit.cssparser.*
com.steadystate.css.parser.CSSOMParser org.htmlunit.cssparser.parser.CSSOMParser
org.w3c.css.sac.* Remove — SAC interfaces replaced by built-in alternatives

Step 3: Adapt SAC-Related Code

Because the SAC dependency has been removed, code that uses SAC interfaces directly needs to be updated:

  • InputSource: Replace org.w3c.css.sac.InputSource with the HtmlUnit-CSSParser equivalent.
  • ErrorHandler: Replace org.w3c.css.sac.ErrorHandler with the built-in error handling mechanism.
  • SACParser classes: Classes like SACParserCSS3 are no longer needed — CSSOMParser handles CSS3 (and beyond) directly.

Step 4: Verify and Test

The core concepts remain the same: the parser reads CSS source text and produces a style tree. Familiar classes like CSSOMParser are preserved. After updating imports and SAC-related code, run your test suite to verify everything works.

Check the HtmlUnit-CSSParser README and release notes for details on any further API differences.

Quick Start Example

Here is a minimal example using HtmlUnit-CSSParser:

import java.io.StringReader;
import org.htmlunit.cssparser.parser.CSSOMParser;
import org.w3c.dom.css.CSSStyleSheet;
import org.w3c.dom.css.CSSRuleList;
import org.w3c.dom.css.CSSRule;

String css = "h1 { background: #ffcc44; } .container { margin: 0 auto; }";
CSSOMParser parser = new CSSOMParser();
CSSStyleSheet sheet = parser.parseStyleSheet(
        new org.htmlunit.cssparser.parser.InputSource(new StringReader(css)),
        null, null);

CSSRuleList rules = sheet.getCssRules();
for (int i = 0; i < rules.getLength(); i++) {
    CSSRule rule = rules.item(i);
    System.out.println(rule.getCssText());
}

Get Started

Staying with CSS Parser

If migrating is not an option right now, CSS Parser remains available and functional at version 0.9.30.

Continued maintenance — including bug fixes, security patches, and compatibility updates — is available through sponsorship. If your project depends on CSS Parser and you need ongoing support, please contact the maintainer via the GitHub page to discuss sponsorship options.