flutter_html_css_object_fit #

A flutter_html extension that renders the CSS object-fit and object-position properties on <img> elements. flutter_html 3.0.0 hardcodes BoxFit.fill in all three of its image renderers, and no parameter or Style field reaches it. This extension replaces the built-in <img> renderer for the images it matches; list it last. object-fit needs an <img> with both a width and a height.

Contents #

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

Features #

• object-position takes one or two keywords, one or two percentages, or a percentage then a keyword. Two keywords come in either order; a keyword cannot come first in a mixed pair.
• The width, the height, the alt fallback on a load error and the box around the image still come from the built-in renderer.

Getting started #

dependencies:
  flutter_html: ^3.0.0
  flutter_html_css_object_fit: ^0.2.0

Usage #

import 'package:flutter_html/flutter_html.dart';
import 'package:flutter_html_css_object_fit/flutter_html_css_object_fit.dart';

Html(
  data: '''
    <img src="https://example.com/photo.jpg"
         width="240" height="80"
         style="object-fit: cover; object-position: 50% 20%;">
  ''',
  extensions: const [CssObjectFitHtmlExtension()],
);

object-fit needs a box to fill. Set both a width and a height in pixels, with the attributes or the inline style, and give the box a different aspect ratio from the image. An <img> with no size, or with only one of the two, is already the shape of its image, and all five values render the same picture. There is no error and no warning.

<!-- object-fit works here -->
<img src="asset:photo.png" width="240" height="80" style="object-fit: cover;">

<!-- and does nothing here -->
<img src="asset:photo.png" style="object-fit: cover;">

Before you register it #

This extension matches an <img> whose inline style carries an object-fit or object-position value it renders. It matches nothing else, and never on a class attribute.

List this extension last. flutter_html builds an element with the first extension in the list that matches it, and this one calls no other, so anything listed after it never sees the <img>. Listed first, the max-width of flutter_html_css_size_constraints 0.1.0 never applies. There is no error and no warning. The image renders at the right fit and the wrong size.

Html(
  data: '<img src="asset:photo.png" width="240" height="80" '
      'style="object-fit: cover; max-width: 120px;">',
  extensions: const [
    CssObjectFitHtmlExtension(),
    CssSizeConstraintsHtmlExtension(), // never runs; max-width never applies
  ],
);

The same rule holds for flutter_html_css_percent_size, which resolves a percentage width or height. List it before this extension. Listed after it, it never runs and the image renders zero pixels wide. Measured with width: 50% in a containing block of 784: 392 wide with it first, 0 wide with it second. There is no error and no warning.

A TagExtension for img is incompatible with this extension, in either order. The TagExtension's widget renders and the object-fit never applies. There is no error and no warning. Use a TagWrapExtension, which wraps the prepared element instead of replacing it. An ImageExtension also renders the whole image. Whichever of the two is listed first wins, and the other never runs. There is no error and no warning.

Released flutter_html_bootstrap 0.1.1 and flutter_html_vuetify 0.1.0 do not recognise CssObjectFitHtmlExtension, so Bootstrap's 30 object-fit-* classes stay suppressed. Set object-fit in an inline style attribute until a release of theirs lists it. No Vuetify class emits object-fit.

Order against flutter_html_css_border_radius 0.1.1, and the measurements behind all of the above: doc/composition.md.

Limitations #

• !important is not read. object-fit: cover !important is not recognised, and the image renders stretched. There is no error and no warning.
• object-fit starts at fill, so an object-position on its own changes nothing. A stretched image leaves no spare space to move it in. There is no error and no warning.
• A percentage width or height renders zero pixels wide, with or without this package. Give it a pixel width and height, or register flutter_html_css_percent_size before this one. There is no error and no warning.
• object-position does not read a length, the three- and four-value edge syntax, calc() or var(). An object-fit in the same inline style still applies.
• <video>, <canvas>, <object> and <iframe> have no renderer in flutter_html 3.0.0, so there is nothing to fit.
• An <img> the built-in renderer declines, an SVG included, this extension declines too. Bare flutter_html renders nothing for those, not even the alt text.
• The extension reads the inline style only. It does not read <style> blocks or stylesheets.

Full list: doc/limitations.md.

Additional information #

Issues and merge requests go to the GitLab repository. Rounding and clipping the same image is flutter_html_css_border_radius's job.

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