From 0d3cfcf0256df6986c4438f2fc021520b69e6a30 Mon Sep 17 00:00:00 2001
From: "Jules Sam. Randolph" <jules.sam.randolph@gmail.com>
Date: Thu, 23 Jul 2020 20:39:24 -0300
Subject: [PATCH] feat: a revamped scalable HTMLImage component
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

BREAKING: imagesMaxWidth prop is discontinued in favor of contentWidth and
computeImagesMaxWidth. See RFC001 for an exhaustive description.

This patch offers a rewrite of the HTMLImage component to get a close
match with RFC001, “a deterministic approach to images scaling”. The only
part of this RFC which is unsupported is the unitConverter behavior, which
is planned for a later major release.

In addition to the capabilities defined in the RFC, this patch provides
the following features and behaviors:

- new property enableExperimentalPercentWidth. It allows percent width
  for <img> tags, computed relatively to contentWidth.
- take margins into account when scaling down images;
- support for overriding image styles, including resizeMode;
- support for minWidth, minHeight, maxWidth, maxHeight styles.

This patch also fixes #141, #172 and provides the features offered in
PR #242 and #315.

OPTIMIZATIONS: The imageBoxDimensions are computed when required. In
addition, requirements are also recomputed when necessary, preventing
expensive operations from happening too often. Also, because we need to
flatten the style prop to infer requirements, this flatten value is now
cached and re-evaluated when appropriate. Finally, styles have been
moved to a stylesheet when that is possible, to avoid commiting updates
to the native side. Note that these performance optimizations are made
possible by the high coverage rate of the HTMLImage component.

fixes #141
fixes #172
closes #315
closes #242
---
 README.md                                     |  93 ++--
 src/HTML.js                                   |  32 +-
 src/HTMLImage.js                              | 490 ++++++++++++++----
 src/HTMLRenderers.js                          | 301 ++++++-----
 src/__mocks__/react-native.js                 |  24 +-
 src/__tests__/README.MD                       |   4 +-
 src/__tests__/component.html.test.js          |  17 +
 src/__tests__/component.image.test.js         | 322 ++++++++++++
 .../regression.141.custom-blur-image.test.js  |   2 +-
 types/react-native-render-html/index.d.ts     |  19 +-
 10 files changed, 999 insertions(+), 305 deletions(-)
 create mode 100644 src/__tests__/component.html.test.js
 create mode 100644 src/__tests__/component.image.test.js

diff --git a/README.md b/README.md
index 84823cad4..3fcdb5576 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,3 @@
-
 [![platforms](https://img.shields.io/badge/platforms-Android%20%7C%20iOS-brightgreen.svg?colorB=191A17)](#)
 [![npm](https://img.shields.io/npm/v/react-native-render-html/latest)](https://www.npmjs.com/package/react-native-render-html)
 [![](https://img.shields.io/npm/v/react-native-render-html/next)](#)
@@ -68,8 +67,8 @@ An iOS/Android pure javascript react-native component that renders your HTML int
 
 ### Stable releases
 
-| Minor | Branch                                                                                  | Documentation                                                                                            | Test Status                                                                                            | Latest                                                                         |
-| ----- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| Minor | Branch                                                                                  | Documentation                                                                                            | Test Status                                                                                             | Latest                                                                         |
+| ----- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
 | 4.2   |  [release/4.2](https://github.com/archriss/react-native-render-html/tree/release/4.2)   | [release/4.2/README.md](https://github.com/archriss/react-native-render-html/blob/release/4.2/README.md) | ![CI](https://github.com/archriss/react-native-render-html/workflows/CI/badge.svg?branch=release%2F4.2) | [![npm](https://img.shields.io/npm/v/react-native-render-html/release/4.2)](#) |
 | 4.1   |  [release/4.1](https://github.com/archriss/react-native-render-html/tree/release/4.1)   | [release/4.1/README.md](https://github.com/archriss/react-native-render-html/blob/release/4.1/README.md) | ![CI](https://github.com/archriss/react-native-render-html/workflows/CI/badge.svg?branch=release%2F4.1) | [![npm](https://img.shields.io/npm/v/react-native-render-html/release/4.1)](#) |
 | 4.0   |  [release/4.0](https://github.com/archriss/react-native-render-html/tree/release/4.0)   | [release/4.0/README.md](https://github.com/archriss/react-native-render-html/blob/release/4.0/README.md) | ![CI](https://github.com/archriss/react-native-render-html/workflows/CI/badge.svg?branch=release%2F4.0) | [![npm](https://img.shields.io/npm/v/react-native-render-html/release/4.0)](#) |
@@ -106,7 +105,7 @@ npm install react-native-render-html
 
 ```javascript
 import React, { Component } from "react";
-import { ScrollView, Dimensions } from "react-native";
+import { ScrollView, useWindowDimensions } from "react-native";
 import HTML from "react-native-render-html";
 
 const htmlContent = `
@@ -116,54 +115,52 @@ const htmlContent = `
     <em style="textAlign: center;">Look at how happy this native cat is</em>
 `;
 
-export default class Demo extends Component {
-  render() {
-    return (
-      <ScrollView style={{ flex: 1 }}>
-        <HTML
-          html={htmlContent}
-          imagesMaxWidth={Dimensions.get("window").width}
-        />
-      </ScrollView>
-    );
-  }
+export default function Demo() {
+  const contentWidth = useWindowDimensions().width;
+  return (
+    <ScrollView style={{ flex: 1 }}>
+      <HTML html={htmlContent} contentWidth={contentWidth} />
+    </ScrollView>
+  );
 }
 ```
 
 ## Props
 
-| Prop                      | Description                                                                                                                                                              | Type                          | Required/Default                                             |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | ------------------------------------------------------------ |
-| `renderers`               | Your [custom renderers](#creating-custom-renderers)                                                                                                                      | `object`                      | Optional, some default ones are supplied (`<a>`, `<img>`...) |
-| `renderersProps`          | Set of props accessible into your [custom renderers](#creating-custom-renderers) in `passProps` (4th argument)                                                           | `object`                      | Optional                                                     |
-| `html`                    | HTML string to parse and render                                                                                                                                          | `string`                      | Required                                                     |
-| `uri`                     | _(experimental)_ remote website to parse and render                                                                                                                      | `string`                      | Optional                                                     |
-| `decodeEntities`          | Decode HTML entities of your content                                                                                                                                     | `bool`                        | Optional, defaults to `true`                                 |
-| `imagesMaxWidth`          | Resize your images to this maximum width, see [images](#images)                                                                                                          | `number`                      | Optional                                                     |
-| `staticContentMaxWidth`   | Set a maximum width to non-responsive content (`<iframe> for instance`)                                                                                                  | `number`                      | Optional                                                     |
-| `imagesInitialDimensions` | Default width and height to display while image's dimensions are being retrieved, see [images](#images)                                                                  | `{ width: 100, height: 100 }` | Optional                                                     |
-| `onLinkPress`             | Fired with the event, the href and an object with all attributes of the tag as its arguments when tapping a link                                                         | `function`                    | Optional                                                     |
-| `onParsed`                | Fired when your HTML content has been parsed. Also useful to tweak your rendering, see [onParsed](#onparsed)                                                             | `function`                    | Optional                                                     |
-| `tagsStyles`              | Provide your styles for specific HTML tags, see [styling](#styling)                                                                                                      | `object`                      | Optional                                                     |
-| `classesStyles`           | Provide your styles for specific HTML classes, see [styling](#styling)                                                                                                   | `object`                      | Optional                                                     |
-| `listsPrefixesRenderers`  | Your custom renderers from `ul` and `ol` bullets, see [lists prefixes](#lists-prefixes)                                                                                  | `object`                      | Optional                                                     |
-| `containerStyle`          | Custom style for the default container of the renderered HTML                                                                                                            | `object`                      | Optional                                                     |
-| `customWrapper`           | Replace the default wrapper with a function that takes your content as the first parameter                                                                               | `function`                    | Optional                                                     |
-| `remoteLoadingView`       | Replace the default loader while fetching a remote website's content                                                                                                     | `function`                    | Optional                                                     |
-| `remoteErrorView`         | Replace the default error if a remote website's content could not be fetched                                                                                             | `function`                    | Optional                                                     |
-| `emSize`                  | The default value in pixels for `1em`                                                                                                                                    | `number`                      | `14`                                                         |
-| `ptSize`                  | The default value in pixels for `1pt`                                                                                                                                    | `number`                      | `1.3`                                                        |
-| `baseFontStyle`           | The default style applied to `<Text>` components                                                                                                                         | `object`                      | `{ fontSize: 14 }`                                           |
-| `allowFontScaling`        | Specifies whether fonts should scale to respect Text Size accessibility settings                                                                                         | `boolean`                     | `true`                                                       |
-| `textSelectable`          | Allow all texts to be selected                                                                                                                                           | `boolean`                     | `false`                                                      |
-| `alterData`               | Target some specific texts and change their content, see [altering content](#altering-content)                                                                           | `function`                    | Optional                                                     |
-| `alterChildren`           | Target some specific nested children and change them, see [altering content](#altering-content)                                                                          | `function`                    | Optional                                                     |
-| `alterNode`               | Target a specific node and change it, see [altering content](#altering-content)                                                                                          | `function`                    | Optional                                                     |
-| `ignoredTags`             | HTML tags you don't want rendered, see [ignoring HTML content](#ignoring-html-content)                                                                                   | `array`                       | Optional, `['head', 'script', ...]`                          |
-| `allowedStyles`           | Allow render only certain CSS style properties and ignore every other. If you have some property both in `allowedStyles` and `ignoredStyles`, it will be ignored anyway. | `array`                       | Optional, everything is allowed by default                   |
-| `ignoredStyles`           | CSS styles from the `style` attribute you don't want rendered, see [ignoring HTML content](#ignoring-html-content)                                                       | `array`                       | Optional                                                     |
-| `ignoreNodesFunction`     | Return true in this custom function to ignore nodes very precisely, see [ignoring HTML content](#ignoring-html-content)                                                  | `function`                    | Optional                                                     |
-| `debug`                   | Prints the parsing result from htmlparser2 and render-html after the initial render                                                                                      | `bool`                        | Optional, defaults to `false`                                |
+| Prop                             | Description                                                                                                                                                                                                                                        | Type                                              | Required/Default                                             |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ |
+| `renderers`                      | Your [custom renderers](#creating-custom-renderers)                                                                                                                                                                                                | `object`                                          | Optional, some default ones are supplied (`<a>`, `<img>`...) |
+| `renderersProps`                 | Set of props accessible into your [custom renderers](#creating-custom-renderers) in `passProps` (4th argument)                                                                                                                                     | `object`                                          | Optional                                                     |
+| `html`                           | HTML string to parse and render                                                                                                                                                                                                                    | `string`                                          | Required                                                     |
+| `uri`                            | _(experimental)_ remote website to parse and render                                                                                                                                                                                                | `string`                                          | Optional                                                     |
+| `decodeEntities`                 | Decode HTML entities of your content                                                                                                                                                                                                               | `bool`                                            | Optional, defaults to `true`                                 |
+| `computeImagesMaxWidth`          | A function which takes `contentWidth` as argument and returns a new width. Can return `Infinity` to denote unconstrained widths.                                                                                                                   | f(number) → number                                | Optional, defaults to the identity function                  |
+| `contentWidth`                   | The width of the HTML content to display. If you don't pass this prop, images might overflow horizontally and take up to all their physical width. The recommended practice is to pass `useWindowDimensions().width` minus any padding or margins. | Optional, defaults to `Dimensions.window().width` |
+| `enableExperimentalPercentWidth` | Support for relative percent-widths. Currently, it only works for images.                                                                                                                                                                          | `boolean`                                         | Optional, defaults to `false`                                |
+| `staticContentMaxWidth`          | Set a maximum width to non-responsive content (`<iframe> for instance`)                                                                                                                                                                            | `number`                                          | Optional                                                     |
+| `imagesInitialDimensions`        | Default width and height to display while image's dimensions are being retrieved, see [images](#images)                                                                                                                                            | `{ width: 100, height: 100 }`                     | Optional                                                     |
+| `onLinkPress`                    | Fired with the event, the href and an object with all attributes of the tag as its arguments when tapping a link                                                                                                                                   | `function`                                        | Optional                                                     |
+| `onParsed`                       | Fired when your HTML content has been parsed. Also useful to tweak your rendering, see [onParsed](#onparsed)                                                                                                                                       | `function`                                        | Optional                                                     |
+| `tagsStyles`                     | Provide your styles for specific HTML tags, see [styling](#styling)                                                                                                                                                                                | `object`                                          | Optional                                                     |
+| `classesStyles`                  | Provide your styles for specific HTML classes, see [styling](#styling)                                                                                                                                                                             | `object`                                          | Optional                                                     |
+| `listsPrefixesRenderers`         | Your custom renderers from `ul` and `ol` bullets, see [lists prefixes](#lists-prefixes)                                                                                                                                                            | `object`                                          | Optional                                                     |
+| `containerStyle`                 | Custom style for the default container of the renderered HTML                                                                                                                                                                                      | `object`                                          | Optional                                                     |
+| `customWrapper`                  | Replace the default wrapper with a function that takes your content as the first parameter                                                                                                                                                         | `function`                                        | Optional                                                     |
+| `remoteLoadingView`              | Replace the default loader while fetching a remote website's content                                                                                                                                                                               | `function`                                        | Optional                                                     |
+| `remoteErrorView`                | Replace the default error if a remote website's content could not be fetched                                                                                                                                                                       | `function`                                        | Optional                                                     |
+| `emSize`                         | The default value in pixels for `1em`                                                                                                                                                                                                              | `number`                                          | `14`                                                         |
+| `ptSize`                         | The default value in pixels for `1pt`                                                                                                                                                                                                              | `number`                                          | `1.3`                                                        |
+| `baseFontStyle`                  | The default style applied to `<Text>` components                                                                                                                                                                                                   | `object`                                          | `{ fontSize: 14 }`                                           |
+| `allowFontScaling`               | Specifies whether fonts should scale to respect Text Size accessibility settings                                                                                                                                                                   | `boolean`                                         | `true`                                                       |
+| `textSelectable`                 | Allow all texts to be selected                                                                                                                                                                                                                     | `boolean`                                         | `false`                                                      |
+| `alterData`                      | Target some specific texts and change their content, see [altering content](#altering-content)                                                                                                                                                     | `function`                                        | Optional                                                     |
+| `alterChildren`                  | Target some specific nested children and change them, see [altering content](#altering-content)                                                                                                                                                    | `function`                                        | Optional                                                     |
+| `alterNode`                      | Target a specific node and change it, see [altering content](#altering-content)                                                                                                                                                                    | `function`                                        | Optional                                                     |
+| `ignoredTags`                    | HTML tags you don't want rendered, see [ignoring HTML content](#ignoring-html-content)                                                                                                                                                             | `array`                                           | Optional, `['head', 'script', ...]`                          |
+| `allowedStyles`                  | Allow render only certain CSS style properties and ignore every other. If you have some property both in `allowedStyles` and `ignoredStyles`, it will be ignored anyway.                                                                           | `array`                                           | Optional, everything is allowed by default                   |
+| `ignoredStyles`                  | CSS styles from the `style` attribute you don't want rendered, see [ignoring HTML content](#ignoring-html-content)                                                                                                                                 | `array`                                           | Optional                                                     |
+| `ignoreNodesFunction`            | Return true in this custom function to ignore nodes very precisely, see [ignoring HTML content](#ignoring-html-content)                                                                                                                            | `function`                                        | Optional                                                     |
+| `debug`                          | Prints the parsing result from htmlparser2 and render-html after the initial render                                                                                                                                                                | `bool`                                            | Optional, defaults to `false`                                |
 
 ## Demo
 
@@ -409,4 +406,4 @@ import { functionName } from "react-native-render-html/src/HTMLUtils";
 
 ## Help
 
-**If you're facing issues whit this library, [take a look at our dedicated document](HELP.adoc).**
\ No newline at end of file
+**If you're facing issues whit this library, [take a look at our dedicated document](HELP.adoc).**
diff --git a/src/HTML.js b/src/HTML.js
index ef889d4b5..cae4f3232 100644
--- a/src/HTML.js
+++ b/src/HTML.js
@@ -37,8 +37,10 @@ export default class HTML extends PureComponent {
         customWrapper: PropTypes.func,
         onLinkPress: PropTypes.func,
         onParsed: PropTypes.func,
-        imagesMaxWidth: PropTypes.number,
+        computeImagesMaxWidth: PropTypes.func,
         staticContentMaxWidth: PropTypes.number,
+        contentWidth: PropTypes.number,
+        enableExperimentalPercentWidth: PropTypes.bool,
         imagesInitialDimensions: PropTypes.shape({
             width: PropTypes.number,
             height: PropTypes.number
@@ -57,8 +59,9 @@ export default class HTML extends PureComponent {
         decodeEntities: true,
         emSize: 14,
         ptSize: 1.3,
+        contentWidth: Dimensions.get('window').width,
         staticContentMaxWidth: Dimensions.get('window').width,
-        imagesMaxWidth: Dimensions.get('window').width,
+        enableExperimentalPercentWidth: false,
         ignoredTags: IGNORED_TAGS,
         ignoredStyles: [],
         baseFontStyle: { fontSize: 14 },
@@ -86,6 +89,16 @@ export default class HTML extends PureComponent {
     componentDidMount () {
         this.mounted = true;
         this.registerDOM();
+        if (__DEV__ && typeof this.props.contentWidth !== 'number') {
+            console.warn(
+                "You should always pass contentWidth prop to properly handle screen rotations " +
+                "and have a seemless support for images scaling. " +
+                "In the meantime, HTML will fallback to Dimensions.window().width, but its " +
+                "layout will become inconsistent after screen rotations. " +
+                "You are encouraged to use useWindowDimensions hook, see: " +
+                "https://reactnative.dev/docs/usewindowdimensions"
+            );
+        }
     }
 
     componentWillUnmount() {
@@ -93,8 +106,13 @@ export default class HTML extends PureComponent {
     }
 
     componentDidUpdate(prevProps, prevState) {
-        const { html, uri, renderers, tagsStyles, classesStyles } = prevProps;
-        let doParseDOM = false;
+        const { html, uri, renderers, tagsStyles, classesStyles, contentWidth, staticContentMaxWidth, computeImagesMaxWidth } = prevProps;
+        let shouldParseDOM = tagsStyles !== this.props.tagsStyles ||
+                             classesStyles !== this.props.classesStyles ||
+                             contentWidth !== this.props.contentWidth ||
+                             staticContentMaxWidth !== this.props.staticContentMaxWidth ||
+                             computeImagesMaxWidth !== this.props.computeImagesMaxWidth ||
+                             this.state.dom !== prevState.dom;
 
         this.generateDefaultStyles(this.props.baseFontStyle);
         if (renderers !== this.props.renderers) {
@@ -104,11 +122,7 @@ export default class HTML extends PureComponent {
             // If the source changed, register the new HTML and parse it
             this.registerDOM(this.props);
         }
-        if (tagsStyles !== this.props.tagsStyles || classesStyles !== this.props.classesStyles) {
-            // If the tagsStyles changed, render again
-            this.parseDOM(this.state.dom, this.props);
-        }
-        if (this.state.dom !== prevState.dom) {
+        if (shouldParseDOM) {
             this.parseDOM(this.state.dom, this.props);
         }
     }
diff --git a/src/HTMLImage.js b/src/HTMLImage.js
index 121753e04..43182f895 100644
--- a/src/HTMLImage.js
+++ b/src/HTMLImage.js
@@ -1,128 +1,396 @@
-import React, { PureComponent } from 'react';
-import { Image, View, Text } from 'react-native';
-import PropTypes from 'prop-types';
+import React, { PureComponent } from "react";
+import { Image, View, Text, StyleSheet } from "react-native";
+import PropTypes from "prop-types";
 
-export default class HTMLImage extends PureComponent {
-    constructor (props) {
-        super(props);
-        this.state = {
-            width: props.imagesInitialDimensions.width,
-            height: props.imagesInitialDimensions.height
-        };
-    }
+const defaultImageStyle = { resizeMode: "cover" };
+const emptyObject = {};
 
-    static propTypes = {
-        source: PropTypes.object.isRequired,
-        alt: PropTypes.string,
-        height: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
-        width: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
-        style: PropTypes.oneOfType([PropTypes.object, PropTypes.array]),
-        imagesMaxWidth: PropTypes.number,
-        imagesInitialDimensions: PropTypes.shape({
-            width: PropTypes.number,
-            height: PropTypes.number
-        })
-    }
+const styles = StyleSheet.create({
+  image: { resizeMode: "cover" },
+  errorBox: {
+    width: 50,
+    height: 50,
+    borderWidth: 1,
+    borderColor: "lightgray",
+    overflow: "hidden",
+    justifyContent: "center",
+  },
+  errorText: { textAlign: "center", fontStyle: "italic" }
+});
 
-    static defaultProps = {
-        imagesInitialDimensions: {
-            width: 100,
-            height: 100
-        }
-    }
+function attemptParseFloat(value) {
+  const result = parseFloat(value);
+  return Number.isNaN(result) ? null : result;
+}
 
-    componentDidMount () {
-        this.mounted = true;
-        this.getImageSize();
+function normalizeSize(
+  dimension,
+  { containerDimension = null, enablePercentWidth = false } = {}
+) {
+  if (
+    dimension === null ||
+    dimension === undefined ||
+    Number.isNaN(dimension)
+  ) {
+    return null;
+  }
+  if (typeof dimension === "number") {
+    return dimension;
+  }
+  if (typeof dimension === "string") {
+    if (
+      dimension.search("%") !== -1 &&
+      enablePercentWidth &&
+      typeof containerDimension === "number"
+    ) {
+      const parsedFloat = attemptParseFloat(dimension);
+      if (Number.isNaN(parsedFloat)) {
+        return null;
+      }
+      return (parsedFloat * containerDimension) / 100;
+    } else if (dimension.trim().match(/^[\d.]+$/)) {
+      return attemptParseFloat(dimension);
     }
+  }
+  return null;
+}
 
-    componentWillUnmount () {
-        this.mounted = false;
-    }
+function extractHorizontalSpace({
+  marginHorizontal,
+  leftMargin,
+  rightMargin,
+  margin,
+} = {}) {
+  const realLeftMargin = leftMargin || marginHorizontal || margin || 0;
+  const realRightMargin = rightMargin || marginHorizontal || margin || 0;
+  return realLeftMargin + realRightMargin;
+}
 
-    componentDidUpdate(prevProps, prevState) {
-        this.getImageSize(this.props);
-    }
+function deriveRequiredDimensionsFromProps({
+  width,
+  height,
+  enablePercentWidth,
+  contentWidth,
+  flatStyle,
+}) {
+  const normalizeOptionsWidth = {
+    enablePercentWidth,
+    containerDimension: contentWidth,
+  };
+  const normalizeOptionsHeight = {
+    enablePercentWidth: false,
+  };
+  const styleWidth = normalizeSize(flatStyle.width, normalizeOptionsWidth);
+  const styleHeight = normalizeSize(flatStyle.height, normalizeOptionsHeight);
+  const widthProp = normalizeSize(width, normalizeOptionsWidth);
+  const heightProp = normalizeSize(height, normalizeOptionsHeight);
+  return {
+    width: typeof widthProp === "number" ? widthProp : styleWidth,
+    height: typeof heightProp === "number" ? heightProp : styleHeight,
+  };
+}
 
-    getDimensionsFromStyle (style, height, width) {
-        let styleWidth;
-        let styleHeight;
-
-        if (height) {
-            styleHeight = height;
-        }
-        if (width) {
-            styleWidth = width;
-        }
-        if (Array.isArray(style)) {
-            style.forEach((styles) => {
-                if (!width && styles['width']) {
-                    styleWidth = styles['width'];
-                }
-                if (!height && styles['height']) {
-                    styleHeight = styles['height'];
-                }
-            });
-        } else {
-            if (!width && style['width']) {
-                styleWidth = style['width'];
-            }
-            if (!height && style['height']) {
-                styleHeight = style['height'];
-            }
-        }
-
-        return { styleWidth, styleHeight };
-    }
+function scaleUp(minDimensions, desiredDimensions) {
+  const aspectRatio = desiredDimensions.width / desiredDimensions.height;
+  if (desiredDimensions.width < minDimensions.width) {
+    return scaleUp(minDimensions, {
+      width: minDimensions.width,
+      height: minDimensions.width / aspectRatio,
+    });
+  }
+  if (desiredDimensions.height < minDimensions.height) {
+    return scaleUp(minDimensions, {
+      height: minDimensions.height,
+      width: minDimensions.height * aspectRatio,
+    });
+  }
+  return desiredDimensions;
+}
 
-    getImageSize (props = this.props) {
-        const { source, imagesMaxWidth, style, height, width } = props;
-        const { styleWidth, styleHeight } = this.getDimensionsFromStyle(style, height, width);
-
-        if (styleWidth && styleHeight) {
-            return this.mounted && this.setState({
-                width: typeof styleWidth === 'string' && styleWidth.search('%') !== -1 ? styleWidth : parseInt(styleWidth, 10),
-                height: typeof styleHeight === 'string' && styleHeight.search('%') !== -1 ? styleHeight : parseInt(styleHeight, 10)
-            });
-        }
-        // Fetch image dimensions only if they aren't supplied or if with or height is missing
-        Image.getSize(
-            source.uri,
-            (originalWidth, originalHeight) => {
-                if (!imagesMaxWidth) {
-                    return this.mounted && this.setState({ width: originalWidth, height: originalHeight });
-                }
-                const optimalWidth = imagesMaxWidth <= originalWidth ? imagesMaxWidth : originalWidth;
-                const optimalHeight = (optimalWidth * originalHeight) / originalWidth;
-                this.mounted && this.setState({ width: optimalWidth, height: optimalHeight, error: false });
-            },
-            () => {
-                this.mounted && this.setState({ error: true });
-            }
-        );
-    }
+function scaleDown(maxDimensions, desiredDimensions) {
+  const aspectRatio = desiredDimensions.width / desiredDimensions.height;
+  if (desiredDimensions.width > maxDimensions.width) {
+    return scaleDown(maxDimensions, {
+      width: maxDimensions.width,
+      height: maxDimensions.width / aspectRatio,
+    });
+  }
+  if (desiredDimensions.height > maxDimensions.height) {
+    return scaleDown(maxDimensions, {
+      height: maxDimensions.height,
+      width: maxDimensions.height * aspectRatio,
+    });
+  }
+  return desiredDimensions;
+}
 
-    validImage (source, style, props = {}) {
-        return (
-            <Image
-              source={source}
-              style={[style, { width: this.state.width, height: this.state.height, resizeMode: 'cover' }]}
-              {...props}
-            />
-        );
+function scale({ minBox, maxBox }, originalBox) {
+  return scaleDown(maxBox, scaleUp(minBox, originalBox));
+}
+
+function sourcesAreEqual(source1, source2) {
+  return (
+    (source1 && source2 && source1.uri === source2.uri) || source1 === source2
+  );
+}
+
+function identity(arg) {
+  return arg;
+}
+
+function computeImageBoxDimensions(params) {
+  const {
+    computeImagesMaxWidth,
+    contentWidth,
+    flattenStyles,
+    imagePhysicalWidth,
+    imagePhysicalHeight,
+    requiredWidth,
+    requiredHeight,
+  } = params;
+  const horizontalSpace = extractHorizontalSpace(flattenStyles);
+  const {
+    maxWidth = Infinity,
+    maxHeight = Infinity,
+    minWidth = 0,
+    minHeight = 0,
+  } = flattenStyles;
+  const imagesMaxWidth =
+    typeof contentWidth === "number"
+      ? computeImagesMaxWidth(contentWidth)
+      : Infinity;
+  const minBox = {
+    width: minWidth,
+    height: minHeight,
+  };
+  const maxBox = {
+    width:
+      Math.min(
+        imagesMaxWidth,
+        maxWidth,
+        typeof requiredWidth === "number" ? requiredWidth : Infinity
+      ) - horizontalSpace,
+    height: Math.min(
+      typeof requiredHeight === "number" ? requiredHeight : Infinity,
+      maxHeight
+    ),
+  };
+  if (typeof requiredWidth === "number" && typeof requiredHeight === "number") {
+    return scale(
+      { minBox, maxBox },
+      {
+        width: requiredWidth,
+        height: requiredHeight,
+      }
+    );
+  }
+  if (imagePhysicalWidth != null && imagePhysicalHeight != null) {
+    return scale(
+      { minBox, maxBox },
+      {
+        width: imagePhysicalWidth,
+        height: imagePhysicalHeight,
+      }
+    );
+  }
+  return null;
+}
+
+export default class HTMLImage extends PureComponent {
+  __cachedFlattenStyles = null;
+  __cachedRequirements = null;
+
+  constructor(props) {
+    super(props);
+    this.invalidateRequirements(props);
+    const state = {
+      imagePhysicalWidth: null,
+      imagePhysicalHeight: null,
+      requiredWidth: this.__cachedRequirements.width,
+      requiredHeight: this.__cachedRequirements.height,
+      imageBoxDimensions: null,
+    };
+    this.state = {
+      ...state,
+      imageBoxDimensions: this.computeImageBoxDimensions(props, state),
+    };
+  }
+
+  static propTypes = {
+    source: PropTypes.object.isRequired,
+    alt: PropTypes.string,
+    height: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+    width: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+    style: PropTypes.oneOfType([PropTypes.object, PropTypes.array]),
+    computeImagesMaxWidth: PropTypes.func.isRequired,
+    contentWidth: PropTypes.number,
+    enableExperimentalPercentWidth: PropTypes.bool,
+    imagesInitialDimensions: PropTypes.shape({
+      width: PropTypes.number,
+      height: PropTypes.number,
+    }),
+  };
+
+  static defaultProps = {
+    enableExperimentalPercentWidth: false,
+    computeImagesMaxWidth: identity,
+    imagesInitialDimensions: {
+      width: 100,
+      height: 100,
+    },
+  };
+
+  invalidateRequirements(props) {
+    const {
+      width,
+      height,
+      contentWidth,
+      enableExperimentalPercentWidth,
+      style
+    } = props;
+    this.__cachedFlattenStyles =
+      StyleSheet.flatten(style) || emptyObject;
+    this.__cachedRequirements = deriveRequiredDimensionsFromProps({
+      width,
+      height,
+      contentWidth,
+      enablePercentWidth: enableExperimentalPercentWidth,
+      flatStyle: this.__cachedFlattenStyles,
+    });
+  }
+
+  computeImageBoxDimensions(props, state) {
+    const { computeImagesMaxWidth, contentWidth } = props;
+    const {
+      imagePhysicalWidth,
+      imagePhysicalHeight,
+      requiredWidth,
+      requiredHeight,
+    } = state;
+    const imageBoxDimensions = computeImageBoxDimensions({
+      flattenStyles: this.__cachedFlattenStyles,
+      computeImagesMaxWidth,
+      contentWidth,
+      imagePhysicalWidth,
+      imagePhysicalHeight,
+      requiredWidth,
+      requiredHeight,
+    });
+    return imageBoxDimensions;
+  }
+
+  componentDidMount() {
+    this.mounted = true;
+    if (this.state.requiredWidth == null || this.state.requiredHeight == null) {
+      this.fetchPhysicalImageDimensions();
     }
+  }
+
+  componentWillUnmount() {
+    this.mounted = false;
+  }
+
+  componentDidUpdate(prevProps, prevState) {
+    const sourceHasChanged = !sourcesAreEqual(
+      prevProps.source,
+      this.props.source
+    );
+    const requirementsHaveChanged =
+      prevProps.width !== this.props.width ||
+      prevProps.height !== this.props.height ||
+      prevProps.style !== this.props.style;
+    const shouldRecomputeImageBox =
+      requirementsHaveChanged ||
+      this.state.imagePhysicalWidth !== prevState.imagePhysicalWidth ||
+      this.state.imagePhysicalHeight !== prevState.imagePhysicalHeight ||
+      this.props.contentWidth !== prevProps.contentWidth ||
+      this.props.computeImagesMaxWidth !== prevProps.computeImagesMaxWidth;
 
-    get errorImage () {
-        return (
-            <View style={{ width: 50, height: 50, borderWidth: 1, borderColor: 'lightgray', overflow: 'hidden', justifyContent: 'center' }}>
-                { this.props.alt ? <Text style={{ textAlign: 'center', fontStyle: 'italic' }}>{ this.props.alt }</Text> : false }
-            </View>
-        );
+    if (requirementsHaveChanged) {
+      this.invalidateRequirements(this.props);
+      this.setState({
+        requiredWidth: this.__cachedRequirements.width,
+        requiredHeight: this.__cachedRequirements.height,
+      });
+    }
+    if (sourceHasChanged) {
+      if (
+        this.__cachedRequirements.width === null ||
+        this.__cachedRequirements.height === null
+      ) {
+        this.fetchPhysicalImageDimensions();
+      }
+    }
+    if (shouldRecomputeImageBox) {
+      this.setState((state, props) => ({
+        imageBoxDimensions: this.computeImageBoxDimensions(props, state),
+      }));
     }
+  }
 
-    render () {
-        const { source, style, passProps } = this.props;
+  fetchPhysicalImageDimensions(props = this.props) {
+    const { source } = props;
+    source && source.uri && Image.getSize(
+      source.uri,
+      (imagePhysicalWidth, imagePhysicalHeight) => {
+        this.mounted &&
+          this.setState({
+            imagePhysicalWidth,
+            imagePhysicalHeight,
+            error: false,
+          });
+      },
+      () => {
+        this.mounted && this.setState({ error: true });
+      }
+    );
+  }
 
-        return !this.state.error ? this.validImage(source, style, passProps) : this.errorImage;
+  renderImage(imageBoxDimensions) {
+    const { source, style } = this.props;
+    return (
+      <Image
+        source={source}
+        style={[defaultImageStyle, style, imageBoxDimensions]}
+        testID="image-layout"
+      />
+    );
+  }
+
+  renderAlt() {
+    return (
+      <View
+        style={styles.errorBox}
+        testID="image-error"
+      >
+        {this.props.alt ? (
+          <Text style={styles.errorText}>
+            {this.props.alt}
+          </Text>
+        ) : (
+          false
+        )}
+      </View>
+    );
+  }
+
+  renderPlaceholder() {
+    return (
+      <View
+        style={this.props.imagesInitialDimensions}
+        testID="image-placeholder"
+      />
+    );
+  }
+
+  render() {
+    const { error, imageBoxDimensions } = this.state;
+    if (error) {
+      return this.renderAlt();
+    }
+    if (imageBoxDimensions === null) {
+      return this.renderPlaceholder();
     }
+    return this.renderImage(imageBoxDimensions);
+  }
 }
diff --git a/src/HTMLRenderers.js b/src/HTMLRenderers.js
index 7e6441c9d..19b4da6d8 100644
--- a/src/HTMLRenderers.js
+++ b/src/HTMLRenderers.js
@@ -1,22 +1,29 @@
-import React from 'react';
-import { TouchableOpacity, Text, View, Platform } from 'react-native';
-import { WebView } from 'react-native-webview';
-import { _constructStyles, _getElementClassStyles } from './HTMLStyles';
-import HTMLImage from './HTMLImage';
+import React from "react";
+import { TouchableOpacity, Text, View, Platform } from "react-native";
+import { WebView } from "react-native-webview";
+import { _constructStyles, _getElementClassStyles } from "./HTMLStyles";
+import HTMLImage from "./HTMLImage";
 
 function getTextProps(passProps) {
-    const { selectable, allowFontScaling } = passProps;
-    return {
-        selectable,
-        allowFontScaling
-    }
+  const { selectable, allowFontScaling } = passProps;
+  return {
+    selectable,
+    allowFontScaling,
+  };
 }
 
 function getImgProps(passProps) {
-  const { imagesMaxWidth, imagesInitialDimensions } = passProps;
+  const {
+    computeImagesMaxWidth,
+    imagesInitialDimensions,
+    enableExperimentalPercentWidth,
+    contentWidth,
+  } = passProps;
   return {
-    imagesMaxWidth,
+    computeImagesMaxWidth,
     imagesInitialDimensions,
+    enableExperimentalPercentWidth,
+    contentWidth
   };
 }
 
@@ -53,144 +60,182 @@ export function a (htmlAttribs, children, convertedCSSStyles, passProps) {
     }
 }
 
-export function img (htmlAttribs, children, convertedCSSStyles, { key, ...passProps } = {}) {
-    if (!htmlAttribs.src) {
-        return false;
-    }
-
-    const style = _constructStyles({
-        tagName: 'img',
-        htmlAttribs,
-        passProps,
-        styleSet: 'IMAGE'
-    });
-    const { src, alt, width, height } = htmlAttribs;
-    return (
-        <HTMLImage
-          source={{ uri: normalizeUri(src) }}
-          alt={alt}
-          width={width}
-          height={height}
-          style={style}
-          key={key}
-          testID="img"
-          {...getImgProps(passProps)}
-        />
-    );
+export function img(
+  htmlAttribs,
+  children,
+  convertedCSSStyles,
+  { key, ...passProps } = {}
+) {
+  if (!htmlAttribs.src) {
+    return false;
+  }
+
+  const style = _constructStyles({
+    tagName: "img",
+    htmlAttribs,
+    passProps,
+    styleSet: "IMAGE",
+  });
+  const { src, alt, width, height } = htmlAttribs;
+  return (
+    <HTMLImage
+      source={{ uri: normalizeUri(src) }}
+      alt={alt}
+      width={width}
+      height={height}
+      style={style}
+      key={key}
+      testID="img"
+      {...getImgProps(passProps)}
+    />
+  );
 }
 
-export function ul (htmlAttribs, children, convertedCSSStyles, passProps = {}) {
-    const style = _constructStyles({
-        tagName: 'ul',
+export function ul(htmlAttribs, children, convertedCSSStyles, passProps = {}) {
+  const style = _constructStyles({
+    tagName: "ul",
+    htmlAttribs,
+    passProps,
+    styleSet: "VIEW",
+  });
+  const {
+    rawChildren,
+    nodeIndex,
+    key,
+    baseFontStyle,
+    listsPrefixesRenderers,
+  } = passProps;
+  const baseFontSize = baseFontStyle.fontSize || 14;
+  const textProps = getTextProps(passProps);
+  children =
+    children &&
+    children.map((child, index) => {
+      const rawChild = rawChildren[index];
+      let prefix = false;
+      const rendererArgs = [
         htmlAttribs,
-        passProps,
-        styleSet: 'VIEW'
-    });
-    const { rawChildren, nodeIndex, key, baseFontStyle, listsPrefixesRenderers } = passProps;
-    const baseFontSize = baseFontStyle.fontSize || 14;
-    const textProps = getTextProps(passProps);
-    children = children && children.map((child, index) => {
-        const rawChild = rawChildren[index];
-        let prefix = false;
-        const rendererArgs = [
-            htmlAttribs,
-            children,
-            convertedCSSStyles,
-            {
-                ...passProps,
-                index
-            }
-        ];
-
-        if (rawChild) {
-            if (rawChild.parentTag === 'ul' && rawChild.tagName === 'li') {
-                prefix = listsPrefixesRenderers && listsPrefixesRenderers.ul ? listsPrefixesRenderers.ul(...rendererArgs) : (
-                    <View style={{
-                        marginRight: 10,
-                        width: baseFontSize / 2.8,
-                        height: baseFontSize / 2.8,
-                        marginTop: baseFontSize / 2,
-                        borderRadius: baseFontSize / 2.8,
-                        backgroundColor: 'black'
-                    }} />
-                );
-            } else if (rawChild.parentTag === 'ol' && rawChild.tagName === 'li') {
-                prefix = listsPrefixesRenderers && listsPrefixesRenderers.ol ? listsPrefixesRenderers.ol(...rendererArgs) : (
-                    <Text {...textProps} style={{ marginRight: 5, fontSize: baseFontSize }}>{ index + 1 })</Text>
-                );
-            }
+        children,
+        convertedCSSStyles,
+        {
+          ...passProps,
+          index,
+        },
+      ];
+
+      if (rawChild) {
+        if (rawChild.parentTag === "ul" && rawChild.tagName === "li") {
+          prefix =
+            listsPrefixesRenderers && listsPrefixesRenderers.ul ? (
+              listsPrefixesRenderers.ul(...rendererArgs)
+            ) : (
+              <View
+                style={{
+                  marginRight: 10,
+                  width: baseFontSize / 2.8,
+                  height: baseFontSize / 2.8,
+                  marginTop: baseFontSize / 2,
+                  borderRadius: baseFontSize / 2.8,
+                  backgroundColor: "black",
+                }}
+              />
+            );
+        } else if (rawChild.parentTag === "ol" && rawChild.tagName === "li") {
+          prefix =
+            listsPrefixesRenderers && listsPrefixesRenderers.ol ? (
+              listsPrefixesRenderers.ol(...rendererArgs)
+            ) : (
+              <Text
+                {...textProps}
+                style={{ marginRight: 5, fontSize: baseFontSize }}
+              >
+                {index + 1})
+              </Text>
+            );
         }
-        return (
-            <View key={`list-${nodeIndex}-${index}-${key}`} style={{ flexDirection: 'row', marginBottom: 10 }}>
-                { prefix }
-                <View style={{ flex: 1 }}>{ child }</View>
-            </View>
-        );
-    });
-    return (
-        <View style={style} key={key}>
-            { children }
+      }
+      return (
+        <View
+          key={`list-${nodeIndex}-${index}-${key}`}
+          style={{ flexDirection: "row", marginBottom: 10 }}
+        >
+          {prefix}
+          <View style={{ flex: 1 }}>{child}</View>
         </View>
-    );
+      );
+    });
+  return (
+    <View style={style} key={key}>
+      {children}
+    </View>
+  );
 }
 export const ol = ul;
 
-export function iframe (htmlAttribs, children, convertedCSSStyles, passProps) {
-    const { staticContentMaxWidth, tagsStyles, classesStyles } = passProps;
+export function iframe(htmlAttribs, children, convertedCSSStyles, passProps) {
+  const { staticContentMaxWidth, tagsStyles, classesStyles } = passProps;
 
-    const tagStyleHeight = tagsStyles.iframe && tagsStyles.iframe.height;
-    const tagStyleWidth = tagsStyles.iframe && tagsStyles.iframe.width;
+  const tagStyleHeight = tagsStyles.iframe && tagsStyles.iframe.height;
+  const tagStyleWidth = tagsStyles.iframe && tagsStyles.iframe.width;
 
-    const classStyles = _getElementClassStyles(htmlAttribs, classesStyles);
-    const classStyleWidth = classStyles.width;
-    const classStyleHeight = classStyles.height;
+  const classStyles = _getElementClassStyles(htmlAttribs, classesStyles);
+  const classStyleWidth = classStyles.width;
+  const classStyleHeight = classStyles.height;
 
-    const attrHeight = htmlAttribs.height ? parseInt(htmlAttribs.height) : false;
-    const attrWidth = htmlAttribs.width ? parseInt(htmlAttribs.width) : false;
+  const attrHeight = htmlAttribs.height ? parseInt(htmlAttribs.height) : false;
+  const attrWidth = htmlAttribs.width ? parseInt(htmlAttribs.width) : false;
 
-    const height = attrHeight || classStyleHeight || tagStyleHeight || 200;
-    const width = attrWidth || classStyleWidth || tagStyleWidth || staticContentMaxWidth;
+  const height = attrHeight || classStyleHeight || tagStyleHeight || 200;
+  const width =
+    attrWidth || classStyleWidth || tagStyleWidth || staticContentMaxWidth;
 
-    const style = _constructStyles({
-        tagName: 'iframe',
-        htmlAttribs,
-        passProps,
-        styleSet: 'VIEW',
-        additionalStyles: [{ height, width }]
-    });
+  const style = _constructStyles({
+    tagName: "iframe",
+    htmlAttribs,
+    passProps,
+    styleSet: "VIEW",
+    additionalStyles: [{ height, width }],
+  });
 
-    const source = htmlAttribs.srcdoc ? { html: htmlAttribs.srcdoc } : { uri: normalizeUri(htmlAttribs.src) };
+   const source = htmlAttribs.srcdoc ? { html: htmlAttribs.srcdoc } : { uri: normalizeUri(htmlAttribs.src) };
 
     return (
         <WebView testID="iframe" key={passProps.key} source={source} style={style} />
     );
 }
 
-export function pre (htlmAttribs, children, convertedCSSStyles, passProps) {
-    return (
-        <Text
-          key={passProps.key}
-          {...getTextProps(passProps)}
-          style={{ fontFamily: Platform.OS === 'android' ? 'monospace' : 'Menlo' }}>
-            { children }
-        </Text>
-    );
+export function pre(htlmAttribs, children, convertedCSSStyles, passProps) {
+  return (
+    <Text
+      key={passProps.key}
+      {...getTextProps(passProps)}
+      style={{ fontFamily: Platform.OS === "android" ? "monospace" : "Menlo" }}
+    >
+      {children}
+    </Text>
+  );
 }
 
-export function br (htlmAttribs, children, convertedCSSStyles, passProps) {
-    return (
-        <Text
-            {...getTextProps(passProps)}
-            style={{ height: 1.2 * passProps.emSize, flex: 1 }}
-            key={passProps.key}
-        >
-            {"\n"}
-        </Text>
-    );
+export function br(htlmAttribs, children, convertedCSSStyles, passProps) {
+  return (
+    <Text
+      {...getTextProps(passProps)}
+      style={{ height: 1.2 * passProps.emSize, flex: 1 }}
+      key={passProps.key}
+    >
+      {"\n"}
+    </Text>
+  );
 }
 
-export function textwrapper (htmlAttribs, children, convertedCSSStyles, { key, ...passProps }) {
-    return (
-        <Text {...getTextProps(passProps)} key={key} style={convertedCSSStyles}>{ children }</Text>
-    );
+export function textwrapper(
+  htmlAttribs,
+  children,
+  convertedCSSStyles,
+  { key, ...passProps }
+) {
+  return (
+    <Text {...getTextProps(passProps)} key={key} style={convertedCSSStyles}>
+      {children}
+    </Text>
+  );
 }
diff --git a/src/__mocks__/react-native.js b/src/__mocks__/react-native.js
index 9445c4e49..94309d3db 100644
--- a/src/__mocks__/react-native.js
+++ b/src/__mocks__/react-native.js
@@ -3,7 +3,27 @@ import { Image as RNImage } from "react-native";
 export * from "react-native";
 
 export class Image extends RNImage {
-  static getSize(source, callback) {
-      setTimeout(() => callback(640, 360), 0);
+  /**
+   * This mock function will parse the uri to find a dimension pattern
+   * width x height such as in:
+   *
+   *     http://image.com/1920x1080
+   * 
+   * and invoke the callback with the extracted dimensions. If none can
+   * be extracted, it will use 640x360.
+   */
+  static getSize(uri, callback) {
+      setTimeout(() => {
+        let dimensions = [0, 0];
+        if (typeof uri === 'string') {
+          const match = /(\d+)x(\d+)/gi.exec(uri);
+          if (!match) {
+            dimensions = [640, 360];
+          } else {
+            dimensions = [parseInt(match[1], 10), parseInt(match[2], 10)];
+          }
+        }
+        callback.apply(null, dimensions);
+      }, 0);
   }
 }
diff --git a/src/__tests__/README.MD b/src/__tests__/README.MD
index 8eba70ef4..8c6885f9f 100644
--- a/src/__tests__/README.MD
+++ b/src/__tests__/README.MD
@@ -13,7 +13,7 @@
 | domain     | description                                                                         |
 | ---------- | ----------------------------------------------------------------------------------- |
 | w3c        | related to w3c standard specifications, such as the CSS and HTML standards          |
-| custom     | related to HTML component customization behavior, usually in the form of props      |
+| component  | related to a component behavior                                                     |
 | regression | testing against regressions&mdash;the name should be the issue identifier on Github |
 
 ### Identifiers
@@ -21,5 +21,5 @@
 | domain     | identifier                 |
 | ---------- | -------------------------- |
 | w3c        | _standard_._rule_          |
-| custom     |                            |
+| component  | _name_                     |
 | regression | _issue-number_._qualifier_ |
diff --git a/src/__tests__/component.html.test.js b/src/__tests__/component.html.test.js
new file mode 100644
index 000000000..ae7a85309
--- /dev/null
+++ b/src/__tests__/component.html.test.js
@@ -0,0 +1,17 @@
+import React from "react";
+import { render } from "react-native-testing-library";
+import HTML from "../HTML";
+import HTMLImage from "../HTMLImage";
+
+describe("HTML component", () => {
+  it("should update HTMLImage contentWidth when contentWidth prop changes", () => {
+    const contentWidth = 300;
+    const nextContentWidth = 200;
+    const { UNSAFE_getByType, update } = render(
+      <HTML html='<img src="https://img.com/1" />' contentWidth={contentWidth} />
+    );
+    expect(UNSAFE_getByType(HTMLImage).props.contentWidth).toBe(contentWidth);
+    update(<HTML html='<img src="https://img.com/1" />' contentWidth={nextContentWidth} />)
+    expect(UNSAFE_getByType(HTMLImage).props.contentWidth).toBe(nextContentWidth);
+  });
+});
diff --git a/src/__tests__/component.image.test.js b/src/__tests__/component.image.test.js
new file mode 100644
index 000000000..509bda24c
--- /dev/null
+++ b/src/__tests__/component.image.test.js
@@ -0,0 +1,322 @@
+import React from "react";
+import { StyleSheet } from "react-native";
+import {
+  render,
+  flushMicrotasksQueue,
+  waitFor,
+} from "react-native-testing-library";
+import HTMLImage from "../HTMLImage";
+
+describe("HTMLImage component", () => {
+  describe("scaling logic", () => {
+    it("should use width and height from styles", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        width: 320,
+        height: 180,
+      };
+      const { findByTestId } = render(
+        <HTMLImage style={style} source={source} />
+      );
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject(style);
+    });
+    it("should use width and height from props", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        width: 320,
+        height: 180,
+      };
+      const { findByTestId } = render(<HTMLImage {...style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject(style);
+    });
+    it("should scale down required dimensions to contentWidth prop when appropriate", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        width: 320,
+        height: 180,
+      };
+      const contentWidth = 160;
+      const { findByTestId } = render(
+        <HTMLImage contentWidth={contentWidth} {...style} source={source} />
+      );
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: contentWidth,
+        height: contentWidth / (style.width / style.height),
+      });
+    });
+    it("should scale the image to contentWidth prop when appropriate when only width or height is required", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        width: 320,
+      };
+      const contentWidth = 160;
+      const { findByTestId } = render(
+        <HTMLImage contentWidth={contentWidth} {...style} source={source} />
+      );
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: contentWidth,
+        height: contentWidth / (640 / 360),
+      });
+    });
+    it("should scale the image down when only width or height is required", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        width: 320,
+      };
+      const { findByTestId } = render(<HTMLImage {...style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 320,
+        height: 180,
+      });
+    });
+    it("should use physical dimensions when no width or height requirements are provided", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const { findByTestId } = render(
+        <HTMLImage contentWidth={800} source={source} />
+      );
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 640,
+        height: 360,
+      });
+    });
+    it("should handle 0-width and height requirements", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        width: 0,
+        height: 0,
+      };
+      const { findByTestId } = render(<HTMLImage {...style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 0,
+        height: 0,
+      });
+    });
+    it("should handle 0-width or height requirements", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        width: 0,
+      };
+      const { findByTestId } = render(<HTMLImage {...style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 0,
+        height: 0,
+      });
+    });
+    it("should handle maxWidth requirements", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        maxWidth: 320,
+      };
+      const { findByTestId } = render(<HTMLImage style={style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 320,
+        height: 180,
+      });
+    });
+    it("should handle maxHeight requirements", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        maxHeight: 180,
+      };
+      const { findByTestId } = render(<HTMLImage style={style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 320,
+        height: 180,
+      });
+    });
+    it("should handle minWidth requirements", async () => {
+      const source = { uri: "http://via.placeholder.com/10x12" };
+      const style = {
+        minWidth: 30,
+      };
+      const { findByTestId } = render(<HTMLImage style={style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 30,
+        height: 36,
+      });
+    });
+    it("should handle minHeight requirements", async () => {
+      const source = { uri: "http://via.placeholder.com/10x12" };
+      const style = {
+        minHeight: 36,
+      };
+      const { findByTestId } = render(<HTMLImage style={style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 30,
+        height: 36,
+      });
+    });
+  });
+  describe("special units", () => {
+    it("should ignore requirements in percentage when enableExperimentalPercentWidth or contentWidth props are not set", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        width: "50%",
+      };
+      const { findByTestId } = render(<HTMLImage {...style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 640,
+      });
+    });
+    it("should support strings for width and height which can be parsed to floats", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        width: "50",
+      };
+      const { findByTestId } = render(<HTMLImage {...style} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 50,
+      });
+    });
+    describe("when given enableExperimentalPercentWidth + contentWidth props", () => {
+      it("should support requirements in percentage", async () => {
+        const source = { uri: "http://via.placeholder.com/640x360" };
+        const contentWidth = 250;
+        const style = {
+          width: "50%",
+        };
+        const { findByTestId } = render(
+          <HTMLImage
+            enableExperimentalPercentWidth
+            contentWidth={250}
+            {...style}
+            source={source}
+          />
+        );
+        const image = await findByTestId("image-layout");
+        expect(image).toBeTruthy();
+        expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+          width: contentWidth * 0.5,
+        });
+      });
+      it("should constrain a percentage width with the value returned by computeImagesMaxWidth", async () => {
+        const source = { uri: "http://via.placeholder.com/640x360" };
+        const contentWidth = 250;
+        const style = {
+          width: "80%",
+        };
+        const { findByTestId } = render(
+          <HTMLImage
+            enableExperimentalPercentWidth
+            computeImagesMaxWidth={(contentWidth) => contentWidth * 0.7}
+            contentWidth={250}
+            {...style}
+            source={source}
+          />
+        );
+        const image = await findByTestId("image-layout");
+        expect(image).toBeTruthy();
+        expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+          width: contentWidth * 0.7,
+        });
+      });
+      it("should ignore percentage heights", async () => {
+        const source = { uri: "http://via.placeholder.com/640x360" };
+        const contentWidth = 250;
+        const style = {
+          height: "10%",
+        };
+        const { findByTestId } = render(
+          <HTMLImage
+            enableExperimentalPercentWidth
+            contentWidth={250}
+            {...style}
+            source={source}
+          />
+        );
+        const image = await findByTestId("image-layout");
+        expect(image).toBeTruthy();
+        expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+          width: contentWidth,
+          height: (360 / 640) * contentWidth,
+        });
+      });
+    });
+  });
+  describe("capabilities regarding spacing", () => {
+    it("should take into account horizontal margins when scaling down", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const style = {
+        margin: 25,
+        marginHorizontal: 30,
+      };
+      const { findByTestId } = render(
+        <HTMLImage contentWidth={200} style={style} source={source} />
+      );
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject({
+        width: 200 - 30 * 2,
+      });
+    });
+  });
+  describe("when changing props", () => {
+    it("should update box width and height when requirements change", async () => {
+      const source = { uri: "http://via.placeholder.com/640x360" };
+      const initialStyle = {
+        width: 640,
+        height: 360,
+      };
+      const nextStyle = {
+        width: 320,
+        height: 180,
+      };
+      const { findByTestId, update } = render(
+        <HTMLImage {...initialStyle} source={source} />
+      );
+      update(<HTMLImage {...nextStyle} source={source} />);
+      const image = await findByTestId("image-layout");
+      expect(image).toBeTruthy();
+      expect(StyleSheet.flatten(image.props.style)).toMatchObject(nextStyle);
+    });
+    it("should update uri and fetch new dimensions when source changes", async () => {
+      const initialSource = { uri: "http://via.placeholder.com/640x360" };
+      const nextSource = { uri: "http://via.placeholder.com/1920x1080" };
+      const { findByTestId, update, getByTestId } = render(
+        <HTMLImage source={initialSource} />
+      );
+      const image1 = await findByTestId("image-layout");
+      expect(image1).toBeTruthy();
+      expect(StyleSheet.flatten(image1.props.style)).toMatchObject({
+        width: 640,
+        height: 360,
+      });
+      update(<HTMLImage source={nextSource} />);
+      await waitFor(() => findByTestId("image-layout"));
+      const image2 = getByTestId("image-layout");
+      expect(image2).toBeTruthy();
+      expect(StyleSheet.flatten(image2.props.style)).toMatchObject({
+        width: 1920,
+        height: 1080,
+      });
+    });
+  });
+});
diff --git a/src/__tests__/regression.141.custom-blur-image.test.js b/src/__tests__/regression.141.custom-blur-image.test.js
index 2b3832f28..148cd41b0 100644
--- a/src/__tests__/regression.141.custom-blur-image.test.js
+++ b/src/__tests__/regression.141.custom-blur-image.test.js
@@ -17,7 +17,7 @@ describe("HTMLImage component should pass regression test #141", () => {
     const imageLayout = queryByTestId("image-layout")
     expect(imageLayout).toBeFalsy();
     await expect(
-        findByTestId("image-layout", { timeout: 10 })
+        findByTestId("image-layout", { timeout: 100 })
     ).resolves.toBeTruthy();
   });
 });
diff --git a/types/react-native-render-html/index.d.ts b/types/react-native-render-html/index.d.ts
index b3ba46dff..2e33e8612 100644
--- a/types/react-native-render-html/index.d.ts
+++ b/types/react-native-render-html/index.d.ts
@@ -84,10 +84,6 @@ declare module "react-native-render-html" {
        * Specifies whether fonts should scale to respect Text Size accessibility settings
        */
       allowFontScaling?: boolean;
-      /**
-       * Resize your images to this maximum width.
-       */
-      imagesMaxWidth?: number;
       /**
        * Your custom renderers.
        */
@@ -117,6 +113,21 @@ declare module "react-native-render-html" {
        * Default width and height to display while image's dimensions are being retrieved.
        */
       imagesInitialDimensions?: ImageDimensions;
+      /**
+       * The width of the HTML content to display. If you don't pass this prop,
+       * images might overflow horizontally and take up to all their physical
+       * width. The recommended practice is to pass
+       * `useWindowDimensions().width` minus any padding or margins.
+       */
+      contentWidth?: number;
+      /**
+       * A function which takes contentWidth as argument and returns a new width. Can return Infinity to denote unconstrained widths.
+       */
+      computeImagesMaxWidth?: (contentWidth: number) => number;
+      /**
+       * Support for relative percent-widths. Currently, it only works for images.
+       */
+      enableExperimentalPercentWidth?: number;
       /**
        * Fired with the event, the href and an object with all attributes of the tag as its arguments when tapping a link
        */