Cascadia Dart

A Dart implementation of the CSS Selector Library, Writte and Extended with Full CSS Selectors Level 3, Level 4, and beyond coverage per the MDN Web Docs.

Flutter-Compatible — works in Dart VM, browsers, and Flutter apps. No browser-specific APIs; pure Dart.

Features

Complete CSS Selector Support — 60+ selectors, 70+ pseudo-classes, and 25+ pseudo-elements from MDN
Full parsing with robust error handling
Selector matching against DOM trees (package:html)
Specificity calculation per CSS Selectors spec
Serialization back to CSS string representation
Combinators — descendant, child, adjacent sibling, general sibling, namespace
Pseudo-elements via parseWithPseudoElements()
Nesting selector (&) for CSS Nesting Module
Shadow DOM selectors (:host, :host(), :host-context(), :has-slotted(), ::slotted(), ::part())
View Transitions pseudo-classes and pseudo-elements
Container Queries and scoping selectors
Anchor Positioning pseudo-classes
Media state pseudo-classes (:playing, :paused, :muted, etc.)
Text-content selectors (:contains(), :containsown(), :matches())
Form validation pseudo-classes
All with null safety and Dart best practices

Installation

Add to your pubspec.yaml:

dependencies:
  cascadia: ^0.8.0

Usage

Basic Queries

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
}

parse() returns a reusable Sel; the query/queryAll helpers take the selector as a string. Import package:html/parser.dart with a prefix, since it also exports a parse function.

Working with Pseudo-elements

// Enable pseudo-elements in parsing
final sel = parseWithPseudoElements('p::first-letter');

Combinators

// Descendant
final descendants = parse('div p');  // all p inside div

// Child
const children = parse('ul > li');   // direct li children of ul

// Adjacent sibling
final adjacent = parse('h1 + p');    // p immediately after h1

// General sibling
const general = parse('h1 ~ p');     // any p after h1

Pseudo-classes

// Structural
parse(':first-child');
parse(':nth-child(2n+1)');
parse(':nth-of-type(3)');
parse(':only-of-type');

// Relational
parse(':has(.error)');           // has descendant with class "error"
parse(':has-child(input)');      // has immediate child input
parse(':is(h1, h2, h3)');        // matches any of these
parse(':where(.foo, .bar)');     // zero specificity
parse(':not(.disabled)');        // negation

// Link
parse(':any-link');              // both visited & unvisited
parse(':local-link');            // same-origin links
parse(':link');                  // unvisited
parse(':visited');               // visited (stub)

// Form
parse(':enabled');
parse(':disabled');
parse(':checked');
parse(':required');
parse(':optional');
parse(':read-only');
parse(':read-write');
parse(':valid');
parse(':invalid');
parse(':in-range');
parse(':out-of-range');
parse(':placeholder-shown');
parse(':autofill');
parse(':indeterminate');
parse(':blank');
parse(':user-valid');
parse(':user-invalid');

// Interaction
parse(':focus');
parse(':focus-visible');
parse(':focus-within');
parse(':hover');                 // stub
parse(':active');                // stub
parse(':target');
parse(':target-within');         // stub

// Element state
parse(':open');                  // details, select, dialog[open]
parse(':modal');                 // dialog[open] modal
parse(':fullscreen');            // fullscreen element
parse(':popover-open');          // popover showing
parse(':default');               // default option/button

// Linguistic
parse(':lang(en)');
parse(':dir(ltr)');
parse(':dir(rtl)');

// Media playback
parse(':playing');
parse(':paused');
parse(':buffering');
parse(':seeking');
parse(':stalled');
parse(':muted');
parse(':volume-locked');
parse(':picture-in-picture');

// Temporal (view timelines)
parse(':current');
parse(':past');
parse(':future');

// View transitions
parse(':target-current');
parse(':target-before');
parse(':target-after');
parse(':active-view-transition');
parse(':active-view-transition-type(slide)');

// Paged media
parse(':left');                  // left-hand page
parse(':right');                 // right-hand page
parse(':first');                 // first page

// Custom element
parse(':defined');

// Other
parse(':root');
parse(':empty');
parse(':heading');               // any h1–h6
parse(':heading(2n+1)');         // headings by position
parse(':interest-source');       // experimental
parse(':interest-target');
parse(':state(private)');        // custom state
parse(':xr-overlay');            // XR overlay

// Shadow DOM
parse(':host');
parse(':host(.foo)');
parse(':host-context(.theme-dark)');
parse(':has-slotted(*)');

Pseudo-elements

// Classic typographic
parseWithPseudoElements('p::first-line');
parseWithPseudoElements('p::first-letter');

// Generated content
parseWithPseudoElements('a::before');
parseWithPseudoElements('a::after');

// Form controls
parseWithPseudoElements('input::file-selector-button');
parseWithPseudoElements('input::placeholder');
parseWithPseudoElements('select::picker-icon');

// Tree-abiding
parseWithPseudoElements('li::marker');
parseWithPseudoElements('details::details-content');

// Shadow DOM
parseWithPseudoElements('::part(header)');
parseWithPseudoElements('::slotted(span)');

// Highlights
parseWithPseudoElements('::selection');
parseWithPseudoElements('::spelling-error');
parseWithPseudoElements('::grammar-error');
parseWithPseudoElements('::highlight(custom)');
parseWithPseudoElements('::search-text');

Specificity

final sel = parse('div.foo#bar[href]');
print(sel.specificity); // (1, 1, 1) — IDs, classes/attributes/pseudo-classes, type selectors

final low = parse(':where(.a, .b)');
print(low.specificity); // (0, 0, 0) — zero specificity

Serialization

final sel = parse('div.foo > p::first-line');
final css = serialize(sel);  // "div.foo > p::first-line"

Namespace Support

// Namespace prefix with pipe separator
parse('svg|rect');           // rect in any namespace
parse('|a');                 // a with no namespace
parse('*|a');                // a in any namespace

Nesting Selector

// The & selector references parent selector(s) in nested CSS
final nesting = parse('.card &');  // parent selector inside nested rule

Flutter Integration

Cascadia works seamlessly in Flutter apps—pure Dart, no browser dependencies. Use it to parse and query HTML/XML data fetched from networks, assets, or generated locally.

With `package:html` (Pure Dart)

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

Future<List<Element>> fetchArticles(String htmlString) async {
  final document = parse(htmlString);
  // Select all article elements with class "post"
  return queryAll(document, 'article.post');
}

// Use in a Flutter widget:
FutureBuilder<List<Element>>(
  future: fetchArticles(htmlResponse),
  builder: (context, snapshot) {
    if (snapshot.hasData) {
      return ListView(
        children: snapshot.data!
            .map((el) => ListTile(
                  title: Text(el.querySelector('h2')?.text ?? ''),
                  subtitle: Text(el.querySelector('p')?.text ?? ''),
                ))
            .toList(),
      );
    }
    return CircularProgressIndicator();
  },
);

With `flutter_html` package

If you're using the flutter_html package to render HTML in Flutter, you can pre-process the HTML with Cascadia to manipulate or extract data before rendering.

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

HtmlData processHtml(String rawHtml) {
  final doc = parse(rawHtml);

  // Remove all ads using CSS selector
  final ads = queryAll(doc, '.ad, .Advertisement, [id*="ad-"]');
  for (final ad in ads) {
    ad.remove();
  }

  // Extract all links
  final links = queryAll(doc, 'a[href]');
  final hrefs = links.map((a) => a.attributes['href']).toList();

  // Convert back to HTML string for flutter_html
  final cleanedHtml = doc.outerHtml;
  return HtmlData(
    html: cleanedHtml,
    linkCount: hrefs.length,
  );
}

Cascadia's selector engine is fast, supports full CSS selectors, and works entirely offline—ideal for Flutter mobile/desktop apps.

Supported Selectors

Type, Class, ID, Universal

Selector	Example	Description
Type selector	`div`	Element by tag name
Universal selector	`*`	Any element
Class selector	`.warning`	Class attribute contains
ID selector	`#header`	ID attribute matches
Namespace separator	`svg\|circle`	Namespace-qualified name

Attribute Selectors

Selector	Example	Description
`[attr]`	`[disabled]`	Attribute present
`[attr=value]`	`[type="text"]`	Exact value
`[attr~=value]`	`[class~="active"]`	Whitespace-separated word
`[attr\|=value]`	`[lang\|="en"]`	Value or `value-*` prefix
`[attr^=value]`	`[href^="https"]`	Starts with
`[attr$=value]`	`[src$=".png"]`	Ends with
`[attr*=value]`	`[title*="info"]`	Contains substring
`[attr!=value]`	`[lang!="fr"]`	Not equal
`[attr#=regex]`	`[id#="^test-"]`	Regex match (non-standard)
`[attr=i]`	`[lang=i]`	Case-insensitive (non-standard)

Combinators

Selector	Example	Description
Descendant	`A B`	B anywhere inside A
Child	`A > B`	B direct child of A
Adjacent sibling	`A + B`	B immediately after A
General sibling	`A ~ B`	B anywhere after A
Selector list	`A, B, C`	Matches if any matches

Pseudo-classes

Tree-structural

:root, :empty, :first-child, :last-child, :only-child, :nth-child(an+b), :nth-last-child(an+b), :first-of-type, :last-of-type, :only-of-type, :nth-of-type(an+b), :nth-last-of-type(an+b)

Relational

:has(selector), :haschild(selector), :is(selector), :where(selector), :not(selector), :matches(regex) / :matchesown(regex), :contains(text) / :containsown(text)

Link & Location

:link, :visited, :any-link, :local-link, :target, :scope

User Interaction

:hover, :active, :focus, :focus-visible, :focus-within

Input & Form

:enabled, :disabled, :checked, :default, :indeterminate, :placeholder-shown, :autofill, :required, :optional, :read-only, :read-write, :valid, :invalid, :in-range, :out-of-range, :user-valid, :user-invalid, :blank, :input

Element Display State

:open, :modal, :fullscreen, :popover-open, :picture-in-picture

Linguistic

:lang(language), :dir(ltr|rtl)

Media Playback

:playing, :paused, :buffering, :seeking, :stalled, :muted, :volume-locked

Temporal (View Timelines)

:current, :past, :future

View Transitions

:target-current, :target-before, :target-after, :active-view-transition, :active-view-transition-type(type)

Paged Media

:left, :right, :first

Custom State

:state(state-name)

Custom Element

:defined

XR (AR/VR)

:xr-overlay

Anchor Positioning

:anchor(name?), :has-anchor

Container Queries & Scoping

:in-container, :ancestor, :parent, :prev-sibling, :next-sibling

Miscellaneous

:heading (any h1–h6) and :heading(an+b) (position-based)

Pseudo-elements

Typographic

::first-line, ::first-letter, ::cue / ::cue(name)

Generated Content

::before, ::after

::placeholder, ::file-selector-button, ::picker / ::picker(), ::picker-icon, ::checkmark, ::details-content

Tree-abiding

::marker, ::backdrop, ::column, ::scroll-button() / ::scroll-button(axis?), ::scroll-marker, ::scroll-marker-group

Shadow DOM

::part(name), ::slotted(selector?)

Highlight

::selection, ::spelling-error, ::grammar-error, ::target-text, ::search-text, ::highlight(name)

View Transitions

::view-transition, ::view-transition-group(name), ::view-transition-image-pair(name), ::view-transition-old(name), ::view-transition-new(name)

API Reference

Top-level Functions

`parse(String selector) → Sel`

Parse a CSS selector string (without pseudo-elements). Returns a 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 selector for repeated matching.

`query(Node root, Sel selector) → Node?`

Find first matching node in the tree.

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

Find all matching nodes in the tree.

Classes

`Sel`

Base interface for all selector objects:

bool match(Node node) — test if a node matches
Specificity get specificity — specificity weight
String toString() — CSS representation

`Specificity`

Triple (a, b, c) representing selector weight:

a — ID selectors
b — class, attribute, pseudo-class selectors
c — type selectors and pseudo-elements

`SelectorGroup`

Combines multiple selectors; matches if any constituent matches.

`CompoundSelector`

Multiple simple selectors on the same element (e.g., div.foo#bar).

`CombinedSelector`

Two selectors joined by a combinator (descendant, child, +, ~).

Selector Types

TagSelector — type selector (div, svg|rect, *)
ClassSelector — .className
IdSelector — #idValue
AttributeSelector — [attr=value], [attr~=value], etc.
PseudoClassSelector — all pseudo-classes
PseudoElement — pseudo-elements (via pseudoElement getter)

Selector support matrix

Some CSS selectors depend on state a static DOM does not carry — what is hovered, what has focus, which links were visited. Rather than silently returning false, Cascadia reports what it needs and matches correctly once you supply it via MatchContext:

final sel = parse('a:hover');
print(sel.support);           // MatchSupport.requiresContext
print(sel.undecidableParts);  // {:hover}

// Supply the state and it just works:
queryAll(doc, 'a:hover', MatchContext(hovered: someAnchor));

// Or fail loudly instead of guessing:
parse(':hover').matchWith(el, MatchContext.strictEmpty); // throws

The table below is generated from the implementation by tool/generate_capability_matrix.dart and verified in CI, so it cannot drift out of step with the code.

Support	Meaning
✅ full	Decided from the DOM alone.
⚙️ needs context	Correct once you pass the required runtime state in a `MatchContext`; without it, treated as a non-match (or throws under `strict: true`).
⬜ parse only	Parses and serializes, but denotes a rendered fragment rather than an element, so it never matches.

Basic

Selector	Support	Notes
`*`	✅ full	matches against the DOM
`div`	✅ full	matches against the DOM
`.cls`	✅ full	matches against the DOM
`#id`	✅ full	matches against the DOM
`[attr]`	✅ full	matches against the DOM
`[attr="v"]`	✅ full	matches against the DOM
`[attr~="v"]`	✅ full	matches against the DOM
`[attr\|="v"]`	✅ full	matches against the DOM
`[attr^="v"]`	✅ full	matches against the DOM
`[attr$="v"]`	✅ full	matches against the DOM
`[attr*="v"]`	✅ full	matches against the DOM
`svg\|rect`	✅ full	matches against the DOM

Combinators

Selector	Support	Notes
`div p`	✅ full	matches against the DOM
`div > p`	✅ full	matches against the DOM
`h1 + p`	✅ full	matches against the DOM
`h1 ~ p`	✅ full	matches against the DOM
`h1, h2`	✅ full	matches against the DOM

Tree-structural

Selector	Support	Notes
`:root`	✅ full	matches against the DOM
`:empty`	✅ full	matches against the DOM
`:first-child`	✅ full	matches against the DOM
`:last-child`	✅ full	matches against the DOM
`:only-child`	✅ full	matches against the DOM
`:nth-child(2n+1)`	✅ full	matches against the DOM
`:nth-last-child(2)`	✅ full	matches against the DOM
`:first-of-type`	✅ full	matches against the DOM
`:last-of-type`	✅ full	matches against the DOM
`:only-of-type`	✅ full	matches against the DOM
`:nth-of-type(2)`	✅ full	matches against the DOM
`:nth-last-of-type(2)`	✅ full	matches against the DOM

Logical

Selector	Support	Notes
`:not(.a)`	✅ full	matches against the DOM
`:is(h1, h2)`	✅ full	matches against the DOM
`:where(.a)`	✅ full	matches against the DOM
`:has(p)`	✅ full	matches against the DOM
`:has(> p)`	✅ full	matches against the DOM

Forms

Selector	Support	Notes
`:enabled`	✅ full	matches against the DOM
`:disabled`	✅ full	matches against the DOM
`:checked`	✅ full	matches against the DOM
`:default`	✅ full	matches against the DOM
`:required`	✅ full	matches against the DOM
`:optional`	✅ full	matches against the DOM
`:read-only`	✅ full	matches against the DOM
`:read-write`	✅ full	matches against the DOM
`:placeholder-shown`	✅ full	matches against the DOM
`:indeterminate`	⚙️ needs context	supply :indeterminate via `MatchContext`
`:valid`	⚙️ needs context	supply :valid via `MatchContext`
`:invalid`	⚙️ needs context	supply :invalid via `MatchContext`
`:in-range`	⚙️ needs context	supply :in-range via `MatchContext`
`:out-of-range`	⚙️ needs context	supply :out-of-range via `MatchContext`
`:user-valid`	⚙️ needs context	supply :user-valid via `MatchContext`
`:user-invalid`	⚙️ needs context	supply :user-invalid via `MatchContext`
`:blank`	⚙️ needs context	supply :blank via `MatchContext`
`:autofill`	⚙️ needs context	supply :autofill via `MatchContext`

Links & location

Selector	Support	Notes
`:any-link`	✅ full	matches against the DOM
`:link`	✅ full	matches against the DOM
`:visited`	⚙️ needs context	supply :visited via `MatchContext`
`:local-link`	⚙️ needs context	supply :local-link via `MatchContext`
`:target`	⚙️ needs context	supply :target via `MatchContext`
`:target-within`	⚙️ needs context	supply :target-within via `MatchContext`
`:scope`	⚙️ needs context	supply :scope via `MatchContext`

Interaction

Selector	Support	Notes
`:hover`	⚙️ needs context	supply :hover via `MatchContext`
`:active`	⚙️ needs context	supply :active via `MatchContext`
`:focus`	⚙️ needs context	supply :focus via `MatchContext`
`:focus-visible`	⚙️ needs context	supply :focus-visible via `MatchContext`
`:focus-within`	⚙️ needs context	supply :focus-within via `MatchContext`

Display state

Selector	Support	Notes
`:open`	✅ full	matches against the DOM
`:modal`	✅ full	matches against the DOM
`:fullscreen`	⚙️ needs context	supply :fullscreen via `MatchContext`
`:popover-open`	⚙️ needs context	supply :popover-open via `MatchContext`
`:defined`	⚙️ needs context	supply :defined via `MatchContext`
`:state(x)`	⚙️ needs context	supply :state(x) via `MatchContext`
`:picture-in-picture`	⚙️ needs context	supply :picture-in-picture via `MatchContext`

Linguistic

Selector	Support	Notes
`:lang(en)`	✅ full	matches against the DOM
`:dir(ltr)`	✅ full	matches against the DOM

Media

Selector	Support	Notes
`:muted`	✅ full	matches against the DOM
`:paused`	✅ full	matches against the DOM
`:playing`	✅ full	matches against the DOM
`:buffering`	⚙️ needs context	supply :buffering via `MatchContext`
`:seeking`	⚙️ needs context	supply :seeking via `MatchContext`
`:stalled`	⚙️ needs context	supply :stalled via `MatchContext`
`:volume-locked`	⚙️ needs context	supply :volume-locked via `MatchContext`

Shadow DOM

Selector	Support	Notes
`:host`	⚙️ needs context	supply :host via `MatchContext`
`:host(.a)`	⚙️ needs context	supply :host(.a) via `MatchContext`
`:host-context(.a)`	⚙️ needs context	supply :host-context(.a) via `MatchContext`
`:has-slotted`	✅ full	matches against the DOM

Non-standard

Selector	Support	Notes
`:contains("x")`	✅ full	matches against the DOM
`:containsown("x")`	✅ full	matches against the DOM
`:matches(/x/)`	✅ full	matches against the DOM
`:matchesown(/x/)`	✅ full	matches against the DOM
`:haschild(p)`	✅ full	matches against the DOM
`:heading`	✅ full	matches against the DOM
`:heading(2n)`	✅ full	matches against the DOM
`:input`	✅ full	matches against the DOM

Pseudo-elements

Selector	Support	Notes
`::before`	⬜ parse only	represents a rendered fragment; never matches a node
`::after`	⬜ parse only	represents a rendered fragment; never matches a node
`::first-line`	⬜ parse only	represents a rendered fragment; never matches a node
`::first-letter`	⬜ parse only	represents a rendered fragment; never matches a node
`::marker`	⬜ parse only	represents a rendered fragment; never matches a node
`::placeholder`	⬜ parse only	represents a rendered fragment; never matches a node
`::selection`	⬜ parse only	represents a rendered fragment; never matches a node
`::backdrop`	⬜ parse only	represents a rendered fragment; never matches a node
`::part(x)`	⬜ parse only	represents a rendered fragment; never matches a node
`::slotted(p)`	⬜ parse only	represents a rendered fragment; never matches a node
`::highlight(x)`	⬜ parse only	represents a rendered fragment; never matches a node
`::view-transition`	⬜ parse only	represents a rendered fragment; never matches a node

Totals: 61 fully supported · 31 context-dependent · 12 parse-only.

Design Notes

Specificity follows CSS Selectors Level 3: :not() and :is() take the maximum specificity of their arguments; :where() is zero; :has() takes the specificity of its contents.
Combinator parsing treats whitespace as descendant combinator; explicit combinators are >, +, ~.
Selector list (, separated) groups alternatives with maximum specificity across all.
String escaping supports hex escapes (\1234), standard backslash escapes, and quoted strings for attribute values.
Text-content selectors (:contains, :containsown, :matches, :matchesown) collect text via DOM traversal.
The library cover almost complete MDN coverage.

Contributing

Contributions are welcome! Please open issues and PRs on the GitHub repository.

Testing

dart test

License

BSD 3-Clause

Cascadia Dart

Features

Installation

Usage

Basic Queries

Working with Pseudo-elements

Combinators

Pseudo-classes

Pseudo-elements

Specificity

Serialization

Namespace Support

Nesting Selector

Flutter Integration

With package:html (Pure Dart)

With flutter_html package

Supported Selectors

Type, Class, ID, Universal

Attribute Selectors

Combinators

Pseudo-classes

Tree-structural

Relational

Link & Location

User Interaction

Input & Form

Element Display State

Linguistic

Media Playback

Temporal (View Timelines)

View Transitions

Paged Media

Custom State

Custom Element

XR (AR/VR)

Anchor Positioning

Container Queries & Scoping

Miscellaneous

Pseudo-elements

Typographic

Generated Content

Form-related

Tree-abiding

Shadow DOM

Highlight

View Transitions

API Reference

Top-level Functions

parse(String selector) → Sel

parseGroup(String selector) → Sel

parseWithPseudoElements(String selector) → Sel

compile(String selector) → Sel

query(Node root, Sel selector) → Node?

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

Classes

Sel

Specificity

SelectorGroup

CompoundSelector

CombinedSelector

Selector Types

Selector support matrix

Basic

Combinators

Tree-structural

Logical

Forms

Links & location

Interaction

Display state

Linguistic

Media

Shadow DOM

Non-standard

Pseudo-elements

Design Notes

Contributing

Testing

License

Libraries

With `package:html` (Pure Dart)

With `flutter_html` package

`parse(String selector) → Sel`

`parseGroup(String selector) → Sel`

`parseWithPseudoElements(String selector) → Sel`

`compile(String selector) → Sel`

`query(Node root, Sel selector) → Node?`

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

`Sel`

`Specificity`

`SelectorGroup`

`CompoundSelector`

`CombinedSelector`