ImageLoader

Notes

An all-purpose image component. Provides "lazy-loading", graceful image fade-in, and flexible sizing. Most of its functionality can be toggled off or worked around via its many props.

To see many of ImageLoader's performance functionality (such as lazy loading and graceful fade-in) you may need to enable network throttling or hard-refresh the browser so the cached images are cleared.

Image loads as follows:

Image Loader render flow chart. Click to enlarge.
Click to enlarge

Props

  • altstring

    Required if image conveys information to the user.

  • heightstring

    Set as an attribute on the rendered tag. Note, since this may be ignored due to height:auto being set in our pattern library global css, a maxHeight style property will also be generated.

  • rolestring

    Role should be set to 'presentation' if image does not convey useful information to the user; do not pass a role if the image is not presenational/decorative.

  • srcstring

    Image source

  • widthstring

    Set as an attribute on the rendered tag

  • constrainWidthbool

    Set to true for images that are known to be smaller than the parent column. Used to hold space with a set width and height div before image has come into viewport.

  • classNamestring

    Applied to the image itself. If includeFallback is enabled, also applies to the fallback.

  • imageOnlyClassNamestring

    Styles the image only when visible.

  • imageWhenHiddenClassNamestring

    Styles the image only when hidden (either loading or behind fallback if includeFallback is enabled)

  • lazyLoad
    shape {
    enabledbool

    True by default. Wraps image in ViewportChecker. If the image lives "above the fold" and never should check the viewport, but should load automatically, set to false. See ViewportChecker documentation for more information.

    xThresholdnumber

    Pixel value threshold for triggering hasBeenInViewport on x-axis. Set to 300 pixels by default. If you set this value, make sure lazyLoad.enabled is set to true. See ViewportChecker for more information.

    yThresholdnumber

    Pixel value threshold for triggering hasBeenInViewport on y-axis. Set to 500 pixels by default. If you set this value, make sure lazyLoad.enabled is set to true. See ViewportChecker for more information.

    }
  • placeholder
    shape {
    altstring

    Provide an alt for the placeholder if it conveys meaningful information to users

    srcstring

    src attribute for the placeholder image

    }

    Props for an optional placeholder image to be used while true image loads. While lazyLoad.enabled is true, it saves space for the image as it comes into viewport. If includeFallback.enabled is true, image will fade in from the placeholder instead of the grey fallback div.

  • wrapInFlex
    shape {
    enabledbool

    Wrap the image in a FlexEmbed component to prevent the page from jumping around as it renders. Defaults to a 1:1 ratio unless you provide flexHeight and flexWidth to create a custom ratio. See the FlexEmbed documentation for more information.

    constrainWidthbool

    For images that are known to be smaller than the parent column, set to true to create a max-width for FlexEmbed parent.

    heightnumber

    Passed through to underlying FlexEmbed components. In combination with width, this provides a ratio to preserve the right amount of flexible space for the image in the layout. See the FlexEmbed documentation for more information.

    widthnumber

    Passed through to underlying FlexEmbed components. In combination with height, this provides a ratio to preserve the right amount of flexible space for the image in the layout. See FlexEmbed documentation for more information.

    flexEmbedWrapperClassNamestring

    If wrapInFlex.enabled is set to true, use this className to style the grandest-parent of the image. See FlexEmbed for more information on how to style.

    }
  • includeFallback
    shape {
    enabledbool

    Wraps the image in a relatively positioned div, and absolutely positions the image with its fallback (grey div or placeholder).

    fallbackClassNamestring

    Class applied to fallback div or placeholder image.

    wrapperClassNamestring

    Applied to the div surrounding the image and its fallback. This wrapper is automatically positioned relatively, so that the absolute image and fallback can travel together.

    }

Most basic usage

Passing standard img attributes will render a normal img tag. Lazyloading is enabled by default, meaning the image will only load once in the viewport.

The actor Bill Murray

Lazy Loading

Adjust the x and y thresholds to control how close to the viewport edge an image should be before beginning to load. Set enabled to false if you don't want lazy loading.

The actor Bill Murray

Wrapped in FlexEmbed

Enabling `wrapInFlex` provides a space into which the image can load without causing layouts to jump.

The actor Bill Murray

Wrap in FlexEmbed and ConstrainWidth

By default, a FlexEmbed will stretch to fill its parent. In cases where your image width is smaller than its parent's width, add the `constrainWidth` option.

The actor Bill Murray

Including Fallback

Including the default fallback without a FlexEmbed requires the parent to have width and height dimensions, since the fallback is an absolutely positioned div.

The actor Bill Murray

Placeholder Image

Instead of your image fading in from a styled div, it can fade in from any image of your choosing.

The actor Bill Murray

Full Capability

The actor Bill Murray

FlexEmbed

Notes

A flexible embed component for use with media embeds – such as videos, slideshows, or even images– that need to retain a specific aspect ratio but adapt to the width of their containing element.

For images, this is a useful way to prevent layouts from shifting during page load, as the space required by an image will be preserved correctly even in responsive layouts.

Use the height and width props to calculate a ratio based on the dimensions of the content in your embed. With no height and width set, FlexEmbed defaults to a 1:1 (square) ratio.

Props

  • classNamestring['']
  • childrennode
  • heightnumber

    The actual height of children. FlexEmbed will calculate a ratio based on this and width. Set to 100 pixels by default.

  • permitOverflowbool[false]

    If the FlexEmbed is for text content (such as a styled heading), you may want to allow the content to overflow the intrinsic aspect ratio you've provided -- just in case! This option uses a float instead of absolute positioning, and may not work correctly when sizing iFrames or padding is applied to the FlexEmbed itself. If possible, provide padding on the children instead.

  • widthnumber

    The actual width of children. FlexEmbed will calculate a ratio based on this and height. Set to 100 pixels by default.

  • style[{}]

Preserve space -- video

Try resizing the browser to confirm that the space preserved for this iFramed video is always the right ratio.

Preserve space -- images

Try resizing the browser and hard reloading the page to confirm that the space preserved for this image is always the right ratio (note that you need to set the image to block instead of inline, else it will have some extra height due to line-height).

Overflowing content

Compare the below FlexEmbeds, identical except for the content. Note that adding permitOverflow accommodates content that would otherwise be clipped by FlexEmbed.

Imagine this a styled content area for a

Big Heading.

Imagine this is

Some very long content.

We want it to

(hopefully) fit

in the aspect ratio box

we provided FlexEmbed (2:1).

But in case it doesn't,

maybe because the translated

version is longer,

it will naturally stretch

open the height of the

FlexEmbed.

ImageState

Notes

ImageState allows you to create a custom handler for images, reacting to any of four states: loading, failed, empty, or complete. The child passed to ImageState should be a function and will receive the current state as an argument, as well as status, and the image source.

Props

  • childrenfunc*

    Required child function that passes in the current status of the loading image.

  • onErrorfunc

    Function to execute in case the image errors out

  • onCompletefunc

    Function to execute once image has completed loading

  • srcstring

    Source for image to load

To see error/failed, adjust ImageState src with an invalid image url