Cascadia

A Dart CSS selector engine (Level 3 & 4)

Key Facts & Overview

Cascadia is a pure-Dart CSS selector engine that parses, matches, and serializes CSS Selectors Level 3 and Level 4 against HTML documents. It is Flutter-compatible (Dart VM, browsers, and Flutter apps), has no browser-specific APIs, and covers 60+ selectors, 70+ pseudo-classes, and 25+ pseudo-elements from MDN.

›Totals: 61 fully supported · 31 context-dependent · 12 parse-only selectors.
›State-dependent selectors (hover, focus, visited) report what they need via MatchContext.
›Pseudo-elements are enabled with parseWithPseudoElements().
›Verified publisher on pub.dev (ayoubzulfiqar.com).

Core Architectural Features

Full CSS Selectors Level 3 & 4 coverage

60+ selectors, 70+ pseudo-classes, 25+ pseudo-elements

Robust parsing with error handling

Specificity calculation per spec

Serialization back to CSS strings

Shadow DOM, container queries, view transitions

Flutter-compatible — pure Dart, no browser APIs

Null-safe, idiomatic Dart

Installation

dependencies:
  cascadia: ^0.8.0

Usage

import 'package:cascadia/cascadia.dart';
import 'package:html/parser.dart' as html;

void main() {
  final doc = html.parse('''
    <div class="container">
      <p class="intro">Hello</p>
      <p>World</p>
      <ul>
        <li>Item 1</li>
        <li>Item 2</li>
      </ul>
    </div>
  ''');

  // Query with a selector string.
  final intros = queryAll(doc, 'p.intro');
  print('Found ${intros.length} matching nodes'); // 1

  // Query the first match only.
  final first = query(doc, 'li');
  print('First item: ${first?.text}'); // Item 1

  // Pre-compile a selector for repeated matching.
  final isListItem = compile('li');
  final allLis = doc.querySelectorAll('*').where(isListItem);
  print('List items: ${allLis.length}'); // 2
}

API Reference

parse(String selector) → Sel

Parse a CSS selector string (without pseudo-elements). Returns a reusable selector object.

parseGroup(String selector) → Sel

Parse a comma-separated selector list. Returns a SelectorGroup.

parseWithPseudoElements(String selector) → Sel

Parse with pseudo-elements enabled. Throws if pseudo-elements appear without this API.

compile(String selector) → Sel

Shorthand for parse(). Pre-compiles a selector for repeated matching.

query(Node root, Sel selector) → Node?

Find the first matching node in the tree.

queryAll(Node root, Sel selector) → List<Node>

Find all matching nodes in the tree.

Resources & Repositories

pub.dev ↗GitHub ↗API Reference ↗Cascadia case study