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 <img /> 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 <img /> 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

Lazy Loading

Wrapped in FlexEmbed

Wrap in FlexEmbed and ConstrainWidth

Including Fallback

Placeholder Image

Full Capability

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

Preserve space -- images

Overflowing content

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