iron-image

iron-image is an element for displaying an image that provides useful sizing and preloading options not found on the standard <img> tag.

The sizing option allows the image to be either cropped (cover) or letterboxed (contain) to fill a fixed user-size placed on the element.

The preload option prevents the browser from rendering the image until the image is fully loaded. In the interim, either the element's CSS background-color can be be used as the placeholder, or the placeholder property can be set to a URL (preferably a data-URI, for instant rendering) for an placeholder image.

The fade option (only valid when preload is set) will cause the placeholder image/color to be faded out once the image is rendered.

Examples:

Basically identical to <img src="..."> tag:

<iron-image src="http://lorempixel.com/400/400"></iron-image>

Will letterbox the image to fit:

<iron-image style="width:400px; height:400px;" sizing="contain"
  src="http://lorempixel.com/600/400"></iron-image>

Will crop the image to fit:

<iron-image style="width:400px; height:400px;" sizing="cover"
  src="http://lorempixel.com/600/400"></iron-image>

Will show light-gray background until the image loads:

<iron-image style="width:400px; height:400px; background-color: lightgray;"
  sizing="cover" preload src="http://lorempixel.com/600/400"></iron-image>

Will show a base-64 encoded placeholder image until the image loads:

<iron-image style="width:400px; height:400px;" placeholder="data:image/gif;base64,..."
  sizing="cover" preload src="http://lorempixel.com/600/400"></iron-image>

Will fade the light-gray background out once the image is loaded:

<iron-image style="width:400px; height:400px; background-color: lightgray;"
  sizing="cover" preload fade src="http://lorempixel.com/600/400"></iron-image>