flutter_html_css_overflow

pub version pipeline license GitLab

A flutter_html extension that renders the CSS overflow, overflow-x and overflow-y properties. flutter_html 3.0.0 parses none of the three. It drops them, and there is no error and no warning, so a tall child renders over whatever sits below. It wraps the built element in a ClipRect. A vertical clip needs a bounded height, and auto and scroll render nothing.

Contents

Features

  • overflow: hidden and overflow: clip wrap the element in a ClipRect that clips both axes.
  • overflow-x and overflow-y clip one axis and leave the other unclipped. As in CSS, visible on the other axis computes to auto.
  • overflow: visible adds no widget.
  • The shorthand takes one or two values, and declarations apply in source order.
  • !important on a declaration resolves.
  • An element whose final inline style holds none of the three properties gets no wrapper.

Getting started

dependencies:
  flutter_html: ^3.0.0
  flutter_html_css_overflow: ^0.2.0

Usage

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

Html(
  data: '''
    <div style="height: 60px; overflow: hidden;">
      A tall image and a long paragraph, cut off at 60 logical pixels.
    </div>
  ''',
  extensions: const [CssOverflowHtmlExtension()],
);

overflow: hidden clips nothing vertically on its own. A box with no height grows to fit its content, so nothing overflows it. There is no error and no warning. Bound the height with height, which flutter_html parses itself, or with max-height, which flutter_html_css_size_constraints 0.1.0 renders. Horizontal overflow needs neither. A child wider than its parent overflows on its own.

Before you register it

This extension matches an element whose inline style names overflow, overflow-x or overflow-y. It matches at the building step only, and never on a tag name.

List this extension before every other extension that wraps at the building step: CssSizeConstraintsHtmlExtension 0.1.0 and CssInteractionHtmlExtension 0.1.0.

// Also needs flutter_html_css_size_constraints.
Html(
  data: '''
    <div style="max-height: 80px; overflow: hidden;">
      A long article teaser, cut to 80 logical pixels.
    </div>
  ''',
  extensions: const [
    CssOverflowHtmlExtension(), // must come first
    CssSizeConstraintsHtmlExtension(),
  ],
);

Both orders clip. In the other order the two extensions delegate to each other until this package's node guard stops the loop. Against flutter_html_css_size_constraints 0.1.0 that built two ConstrainedBox widgets and a percentage max-height resolved against the wrong one; from 0.1.1 it builds one. Keep the order above anyway. There is no error and no warning.

extensions: const [
  CssSizeConstraintsHtmlExtension(), // runs twice; a percentage max-height is wrong
  CssOverflowHtmlExtension(),
],

List a TagExtension after this extension. flutter_html builds an element with the first extension in the list that matches it. A TagExtension matches on the tag name at every step. Listed first, it builds the element itself and the clip never applies. There is no error and no warning.

extensions: [
  TagExtension(tagsToExtend: const {'v-card'}, child: const Text('Card')), // clip never applies
  const CssOverflowHtmlExtension(),
],

Order does not matter against flutter_html_css_border_radius 0.1.1, whose corners stay round in either order, or against a utility-class extension. The composition notes cover both, and Bootstrap's .text-truncate.

Released flutter_html_bootstrap 0.1.1 and flutter_html_vuetify 0.1.0 do not recognise CssOverflowHtmlExtension. Both therefore still suppress the classes this extension could render. Write overflow into an inline style attribute until a release of theirs lists it.

Limitations

  • auto, scroll and the legacy overlay render nothing. A scroll view needs its main axis bounded from outside, and here the bound arrives from inside, so it scrolls nowhere. The content stays reachable. There is no error and no warning.
  • An inline element gets no clip. flutter_html builds a box for a block, inline-block or list-item element and a TextSpan for everything else. Put the property on the block element. There is no error and no warning.
  • An empty block element gets no clip for the same reason. There is no error and no warning.
  • The clip sits at the border edge, not the padding edge as in CSS.
  • A shorthand with three or more values renders nothing. An unreadable longhand leaves that axis as it was. There is no error and no warning.
  • overflow-clip-margin is not read. overflow: clip clips at the box edge, like overflow: hidden.
  • The extension reads the inline style only. It does not read <style> blocks or stylesheets.

The full reasoning for each one is on the symbol that implements it.

Additional information

Issues and merge requests go to the GitLab repository. The height bound usually comes from flutter_html_css_size_constraints.

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

Libraries

flutter_html_css_overflow