flutter_html_class_to_css #

The plumbing for flutter_html extensions that turn an element's class="..." attribute into inline CSS. flutter_html 3.0.0 carries no utility-class vocabulary, and this package carries none either. It runs the resolvers you give it and merges the result into style="". An element on a tag flutter_html cannot render still renders nothing, whatever the classes resolve to.

Contents #

• Features
• Getting started
• Usage
• Before you register it
• Limitations
• Additional information

Features #

• ClassListCssResolver maps an ordered class list to inline CSS declarations, through its matches and resolve methods.
• ClassToInlineCssExtension runs the resolvers and merges their output into the element's style="", at flutter_html's preStyling step. The result flows through the normal styling pipeline.
• The element's own style="" is kept. Resolved declarations are appended after it, and win where both name the same property.
• An element with no matching class is left alone.
• Resolver order decides the winner when two resolvers write the same property. The later resolver wins.
• The extension names the tags flutter_html renders as nothing, once per parsed document.

Getting started #

dependencies:
  flutter_html: ^3.0.0
  flutter_html_class_to_css: ^0.2.0

Usage #

Write a resolver, then expose it as an extension.

import 'package:flutter/material.dart';
import 'package:flutter_html/flutter_html.dart';
import 'package:flutter_html_class_to_css/flutter_html_class_to_css.dart';

class HighlightResolver implements ClassListCssResolver {
  @override
  bool matches(List<String> orderedClasses) =>
      orderedClasses.contains('highlight');

  @override
  String resolve(List<String> orderedClasses) => 'background-color: #ffff00';
}

class HighlightExtension extends ClassToInlineCssExtension {
  const HighlightExtension({super.reportUnrenderableTags});

  @override
  List<ClassListCssResolver> get resolvers => [HighlightResolver()];
}

Html(
  data: '<div class="highlight" style="padding: 8px;">Highlighted</div>',
  extensions: const [HighlightExtension()],
);

Before you register it #

flutter_html renders an element only if an extension or a built-in claims it at the preparing step. The built-ins claim 70 tags. table and the other table tags, video, audio, iframe, input, svg, math and every custom element are outside that set. An unclaimed element becomes an EmptyContentElement, which drops the element and its whole subtree. There is no error and no warning.

supportedTags does not fix this. flutter_html reads that set in one place, the default HtmlExtension.matches, and ClassToInlineCssExtension overrides matches. Register a TagExtension instead.

Html(
  data: '<v-card class="highlight">Card</v-card>',
  extensions: [
    const HighlightExtension(),
    TagExtension.inline(
      tagsToExtend: const {'v-card'}, // without this, nothing renders
      builder: (context) => TextSpan(children: context.inlineSpanChildren),
    ),
  ],
);

The extension reports the offending tags once per parsed document through FlutterError.reportError. It reports, and never throws. Silence it with HighlightExtension(reportUnrenderableTags: false). The 70 tags, the four measured cases and the reasons for each are in doc/renderable-tags.md.

List this extension before every extension that reads the style attribute at the preStyling step, such as flutter_html_css_border_radius. flutter_html runs every matching extension at that step in registration order, so one listed first reads a style="" this extension has not written to yet. Order against a TagExtension does not matter: this extension matches at the preStyling step only.

Released flutter_html_bootstrap 0.1.1 and flutter_html_vuetify 0.1.0 build on 0.1.0 of this package. Both override beforeStyle and never call recordUnrenderableTag, so neither reports an unrenderable tag yet. Both still report the utility classes they suppress, through FlutterError.

Limitations #

• Only the class attribute is read. A resolver sees class names, never a <style> block, a stylesheet or the element's own style.
• A resolver returns a string. This package parses no CSS and validates nothing a resolver produces.
• flutter_html 3.0.0 drops a font-size written in rem while it parses the style attribute, so a resolver cannot emit one. A px, em or % font size survives; em and % resolve against the parent font size after flutter_html's styling, and the root font size is 14. flutter_html_css_font_size will close this gap.
• The 70-tag set is hardcoded, because flutter_html exposes no way to read it. Re-derive it when the flutter_html dependency moves past 3.0.0.

Additional information #

Built on this package: flutter_html_bootstrap and flutter_html_vuetify.

Issues and merge requests go to the GitLab repository.

CI, publishing and Renovate are described in CONTRIBUTING.md.