[BUG] Build broken by html 0.15.7: Method not found: 'matches' in styled_element.dartError

[Arashecash]

Title: Build broken by html 0.15.7: Method not found: 'matches' in styled_element.dart

---

Describe the bug:

flutter_html 3.0.0 fails to compile against html 0.15.7 (published 2026-08-28).

styled_element.dart imports package:html's private implementation file and calls its top-level matches():

// ignore: implementation_imports
import 'package:html/src/query_selector.dart' as qs;
...
return qs.matches(element, selector);   // line 31

html 0.15.7 removed that top-level matches() function from lib/src/query_selector.dart. Only the SelectorEvaluator.matches method remains, and SelectorEvaluator is not exported publicly either. Because the symbol was private, the removal is not listed as breaking in the html changelog.

flutter_html declares html: ^0.15.5, which admits 0.15.7, so every fresh dependency resolve since 28 August breaks the build. Projects that do not commit pubspec.lock hit this with no change of their own.

HTML to reproduce the issue: n/a - this is a compile-time failure. No HTML or widget is reached.

Html widget configuration: n/a - the app fails to build before any widget is constructed. Reproduce with any project that depends on flutter_html:

flutter pub upgrade html   # resolves to 0.15.7
flutter test               # or flutter build

Expected behavior:

flutter_html 3.0.0 builds against the versions its own constraint allows.

Device details and Flutter/Dart/flutter_html versions:

• flutter_html 3.0.0
• html 0.15.7 (fails) / 0.15.6 (works)
• Flutter 3.38.3 stable, Dart 3.10.1
• macOS - platform independent, it is a compile error

Stacktrace/Logcat

../../../.pub-cache/hosted/pub.dev/flutter_html-3.0.0/lib/src/tree/styled_element.dart:31:17:
Error: Method not found: 'matches'.
      return qs.matches(element, selector);
                ^^^^^^^

Additional info:

Workaround for users: pin the transitive dependency.

dependencies:
  html: 0.15.6

Possible fixes, in case they help:

1. Tighten the constraint to html: '>=0.15.5 <0.15.7' as an immediate unblock.
2. Replace the implementation import with a local selector-match helper, so flutter_html no longer depends on html's private API.
3. Ask the html package to expose matches() publicly - there is currently no public equivalent (Node.querySelector / querySelectorAll exist, but nothing answers "does this element match this selector").

[gopalmak]

@a1rwulf This issue needs to be fix immediate because most of developers are used this package/plugin and they all are blocked by this error to migrate latest Flutter version.

[a1rwulf]

@a1rwulf This issue needs to be fix immediate because most of developers are used this package/plugin and they all are blocked by this error to migrate latest Flutter version.

See: #1515 (comment)

[a1rwulf]

Also:
#1517
#1516

Others already started to do the right thing, instead of complaining and proposed a fix.
Problem is that only one person can merge them.

[sinhar1227]

Actually, the issue is caused by the html dependency package(a new release 10 days ago). I added a dependency override, and it’s working well for me now.

dependency_overrides:
html: 0.15.5

[a1rwulf]

Actually, the issue is caused by the html dependency package(a new release 10 days ago). I added a dependency override, and it’s working well for me now.

dependency_overrides: html: 0.15.5

Yes that has been outlined by the comments before.
The quick and dirty hack around the issue is to downgrade the html dependency to a version that still has the used matches method.
The proper fix is to remove usage of this method, as proposed by the 2 PRs I linked above.

Anyway, it needs the current maintainer to merge them and release an update.

[gopalmak]

Okay, I find the alternate plugin and it's working as expected.

[milekpl]

I can reproduce this on Windows with Flutter 3.47.3 / Dart 3.13.3:

flutter_html 3.0.0
html 0.15.7

The build fails in styled_element.dart because qs.matches no longer exists.
Adding this workaround makes the Windows build succeed:

dependency_overrides:
html: 0.15.6

The proper fix appears to be removing the dependency on
package:html/src/query_selector.dart and replacing the selector matching logic.

[fx-vn]

Last compatible version of html is 0.15.6. It still has a top level matches function.

Packge flutter_html should not rely on implementation code under lib/src of html package.
They even put a warning that this could happen in file 'styled_element.dart', the one that fails.

//TODO(Sub6Resources): don't use the internal code of the html package as it may change unexpectedly.
//ignore: implementation_imports
import 'package:html/src/query_selector.dart' as qs;

As others said, the solution is to change the pubspec.yaml to avoid version 0.15.7 of html.

[soufianebenyaala]

Unfortunately, this issue has completely blocked my development and prevented me from uploading a new version of my app to the Google Play Store. I need to release an urgent hotfix, but the build is now failing because html 0.15.7 is incompatible with flutter_html 3.0.0.

Please consider merging the existing fixes and publishing a new release as soon as possible. This is currently blocking production releases for projects using flutter_html.