- [customImageRender](#customimagerender)

- [typedef ImageSourceMatcher (with examples)](#typedef-imagesourcematcher)

- [typedef ImageRender (with examples)](#typedef-imagerender)

- [Examples](#example-usages---customimagerender)

| `customImageRender` | A powerful API that allows you to fully customize how images are loaded. |

A powerful API that allows you to customize what the `Html` widget does when rendering an image, down to the most minute detail.

`customImageRender` accepts a `Map<ImageSourceMatcher, ImageRender>`. `ImageSourceMatcher` provides the matching function, while `ImageRender` provides the widget to be rendered.

The default image renders are:

See [the source code](https://github.com/Sub6Resources/flutter_html/blob/master/lib/image_render.dart) for details on how these are implemented.

When setting `customImageRenders`, the package will prioritize the custom renders first, while the default ones are used as a fallback.

Note: Order is very important when you set `customImageRenders`. The more specific your `ImageSourceMatcher`, the higher up in the `customImageRender` list it should be.

This is type defined as a function that passes the attributes as a `Map<String, String>` and the DOM element as `dom.Element`. This type is used to define how an image should be matched i.e. whether the package should override the default rendering method and instead use your custom implementation.

A typical usage would look something like this:

In the above example, the matcher checks whether the image's `src` either starts with "data:image" or contains "base64,", since these indicate an image in base64 format.

You can also declare your own variables in the function itself, which would look like this:

In the above example, the possible schemas are checked against the scheme of the `src`, and optionally the domains and extensions are also checked. This implementation allows for extremely granular control over what images are matched, and could even be changed on the fly with a variable.

This is a type defined as a function that passes the attributes of the image as a `Map<String, String>`, the current [`RenderContext`](https://github.com/Sub6Resources/flutter_html/wiki/All-About-customRender#rendercontext-context), and the DOM element as `dom.Element`. This type is used to define the widget that should be rendered when used in conjunction with an `ImageSourceMatcher`.

A typical usage might look like this:

The above example should be used with the `base64UriMatcher()` in the examples for `ImageSourceMatcher`.

Just like functions for `ImageSourceMatcher`, you can declare your own variables in the function itself:

Implementing these variables allows you to customize every last detail of how the widget is rendered.

`customImageRender` can be used in two different ways:

1. Overriding a default render:

Above, there are two `networkSourceMatcher`s. One is overriden to only apply to images on the URL `flutter.dev`, while the other covers the rest of the cases.

When an image with URL `flutter.dev` is detected, rather than displaying the image, the render will display the flutter logo. If the image is any other image, it keeps the default widget, but just sets the headers and the alt text in case that image happens to be broken.

2. Creating your own renders:

The above example has a matcher that checks for either a class or an id, and then returns two different widgets based on whether a class was matched or an id was matched.

The sky is the limit when using the custom image renders. You can make it as granular as you want, or as all-encompassing as you want, and you have full control of everything. Plus you get the package's style parsing to use in your custom widgets, so your code looks neat and readable!