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:

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.

}

Example: Most basic usage

<React.Fragment>
  <p className="pb5">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.</p>
  <ImageLoader
    src="https://via.placeholder.com/300x250"
    alt="The actor Bill Murray"
    width="200"
  />
</React.Fragment>

<React.Fragment>
  <p className="pb5">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.</p>
  <ImageLoader
    src="https://via.placeholder.com/300x250"
    alt="The actor Bill Murray"
    width="200"
  />
</React.Fragment>

Example: Lazy Loading

<React.Fragment>
  <p className="pb5">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.</p>
  <ImageLoader
    src="https://via.placeholder.com/400x300"
    alt="The actor Bill Murray"
    lazyLoad={{
      enabled: true,
      xThreshold: 300,
      yThreshold: 20
    }}
  />
</React.Fragment>

<React.Fragment>
  <p className="pb5">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.</p>
  <ImageLoader
    src="https://via.placeholder.com/400x300"
    alt="The actor Bill Murray"
    lazyLoad={{
      enabled: true,
      xThreshold: 300,
      yThreshold: 20
    }}
  />
</React.Fragment>

Example: Wrapped in FlexEmbed

<div style={{maxWidth: '700px'}}>
  <p className="pb5">
    Enabling `wrapInFlex` provides a space into which the image can load without causing layouts to jump.
  </p>
  <ImageLoader
    wrapInFlex={{
      enabled: true,
      width: 700,
      height: 500
    }}
    src="https://via.placeholder.com/700x500"
    alt="The actor Bill Murray"
  />
</div>

<div style={{maxWidth: '700px'}}>
  <p className="pb5">
    Enabling `wrapInFlex` provides a space into which the image can load without causing layouts to jump.
  </p>
  <ImageLoader
    wrapInFlex={{
      enabled: true,
      width: 700,
      height: 500
    }}
    src="https://via.placeholder.com/700x500"
    alt="The actor Bill Murray"
  />
</div>

Example: Wrap in FlexEmbed and ConstrainWidth

<div>
  <p className="pb5">
    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.
  </p>
  <ImageLoader
    wrapInFlex={{
      enabled: true,
      width: 200,
      height: 200,
      constrainWidth: true
    }}
    src="https://via.placeholder.com/200x200"
    alt="The actor Bill Murray"
  />
</div>

<div>
  <p className="pb5">
    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.
  </p>
  <ImageLoader
    wrapInFlex={{
      enabled: true,
      width: 200,
      height: 200,
      constrainWidth: true
    }}
    src="https://via.placeholder.com/200x200"
    alt="The actor Bill Murray"
  />
</div>

Example: Including Fallback

<React.Fragment>
  <p className="pb5">
    Including the default fallback without a FlexEmbed requires the parent to have width and height dimensions, since the fallback is an absolutely positioned div. 
  </p>
  <div style={{height:'300px', width: '300px', margin: 'auto'}}>
    <ImageLoader
      src="https://via.placeholder.com/300x300"
      includeFallback={{
        enabled: true,
        fallbackClassName: 'bg-greenAccent'
      }}
      alt="The actor Bill Murray"
    />
  </div>
</React.Fragment>

<React.Fragment>
  <p className="pb5">
    Including the default fallback without a FlexEmbed requires the parent to have width and height dimensions, since the fallback is an absolutely positioned div. 
  </p>
  <div style={{height:'300px', width: '300px', margin: 'auto'}}>
    <ImageLoader
      src="https://via.placeholder.com/300x300"
      includeFallback={{
        enabled: true,
        fallbackClassName: 'bg-greenAccent'
      }}
      alt="The actor Bill Murray"
    />
  </div>
</React.Fragment>

Example: Placeholder Image

<div>
  <p className="pb5">
    Instead of your image fading in from a styled div, it can fade in from any image of your choosing.
  </p>
  <ImageLoader
    src="https://via.placeholder.com/325x325"
    placeholder={{
      src: "https://via.placeholder.com/325"
    }}
    includeFallback={{
      enabled: true
    }}
    wrapInFlex={{
      enabled: true,
      width: 325,
      height: 325,
      constrainWidth: true
    }}
    alt="The actor Bill Murray"
  />
</div>

<div>
  <p className="pb5">
    Instead of your image fading in from a styled div, it can fade in from any image of your choosing.
  </p>
  <ImageLoader
    src="https://via.placeholder.com/325x325"
    placeholder={{
      src: "https://via.placeholder.com/325"
    }}
    includeFallback={{
      enabled: true
    }}
    wrapInFlex={{
      enabled: true,
      width: 325,
      height: 325,
      constrainWidth: true
    }}
    alt="The actor Bill Murray"
  />
</div>

Example: Full Capability

<ImageLoader
    alt="The actor Bill Murray"
    src="https://via.placeholder.com/400x400"
    includeFallback={{
      enabled: true
    }}
    wrapInFlex={{
      enabled: true,
      width: 400,
      height: 400,
      constrainWidth: true
    }}
    lazyLoad={{
      enabled: true,
      yThreshold: 50,
      xThreshold: 100
    }}
  />

<ImageLoader
    alt="The actor Bill Murray"
    src="https://via.placeholder.com/400x400"
    includeFallback={{
      enabled: true
    }}
    wrapInFlex={{
      enabled: true,
      width: 400,
      height: 400,
      constrainWidth: true
    }}
    lazyLoad={{
      enabled: true,
      yThreshold: 50,
      xThreshold: 100
    }}
  />

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[{}]

Example: Preserve space -- video

<div>
  <p className="p5">Try resizing the browser to confirm that the space preserved for this iFramed video is always the right ratio.</p>
  <FlexEmbed height={ 315 } width={ 560 } className="bg-houseGreen">
    <iframe
      title="this is a video of happy people"
      width="100%"
      height="100%"
      src="https://www.youtube.com/embed/mYdpsbfW-Fw"
      frameBorder="0"
    />
  </FlexEmbed>
</div>

<div>
  <p className="p5">Try resizing the browser to confirm that the space preserved for this iFramed video is always the right ratio.</p>
  <FlexEmbed height={ 315 } width={ 560 } className="bg-houseGreen">
    <iframe
      title="this is a video of happy people"
      width="100%"
      height="100%"
      src="https://www.youtube.com/embed/mYdpsbfW-Fw"
      frameBorder="0"
    />
  </FlexEmbed>
</div>

Example: Preserve space -- images

<div>
  <p className="p5">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).</p>
  <FlexEmbed className="bg-houseGreen" width={ 800 } height={ 300 }>
    <img
      className='block'
      src='https://via.placeholder.com/800x300'
      alt=''
    />
  </FlexEmbed>
</div>

<div>
  <p className="p5">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).</p>
  <FlexEmbed className="bg-houseGreen" width={ 800 } height={ 300 }>
    <img
      className='block'
      src='https://via.placeholder.com/800x300'
      alt=''
    />
  </FlexEmbed>
</div>

Example: Overflowing content

<div>
  <p className="pt3">Compare the below FlexEmbeds, identical except for the content. Note that adding permitOverflow accommodates content that would otherwise be clipped by FlexEmbed.</p> 
  <FlexEmbed permitOverflow width={4} height={2} className="my5 bg-houseGreen color-textWhite">
    <div className="p5">
      <p className="my5">Imagine this a styled content area for a</p>
      <p className="my5"><span className="text-xxxl">Big Heading</span>.</p>
    </div>
  </FlexEmbed>

  <FlexEmbed permitOverflow width={4} height={2} className="my5 bg-houseGreen color-textWhite">
    <div className="p5">
      <p className="my5">Imagine this is</p>
      <p className="my5">Some very long content.</p>
      <p className="my5">We want it to</p>
      <p className="my5">(hopefully) fit</p>
      <p className="my5">in the aspect ratio box</p>
      <p className="my5">we provided FlexEmbed (2:1).</p>
      <p className="my5">But in case it doesn't,</p>
      <p className="my5">maybe because the translated</p>
      <p className="my5">version is longer,</p>
      <p className="my5">it will naturally stretch</p>
      <p className="my5">open the height of the</p>
      <p className="my5">FlexEmbed.</p>
    </div>
  </FlexEmbed>
</div>

<div>
  <p className="pt3">Compare the below FlexEmbeds, identical except for the content. Note that adding permitOverflow accommodates content that would otherwise be clipped by FlexEmbed.</p> 
  <FlexEmbed permitOverflow width={4} height={2} className="my5 bg-houseGreen color-textWhite">
    <div className="p5">
      <p className="my5">Imagine this a styled content area for a</p>
      <p className="my5"><span className="text-xxxl">Big Heading</span>.</p>
    </div>
  </FlexEmbed>

  <FlexEmbed permitOverflow width={4} height={2} className="my5 bg-houseGreen color-textWhite">
    <div className="p5">
      <p className="my5">Imagine this is</p>
      <p className="my5">Some very long content.</p>
      <p className="my5">We want it to</p>
      <p className="my5">(hopefully) fit</p>
      <p className="my5">in the aspect ratio box</p>
      <p className="my5">we provided FlexEmbed (2:1).</p>
      <p className="my5">But in case it doesn't,</p>
      <p className="my5">maybe because the translated</p>
      <p className="my5">version is longer,</p>
      <p className="my5">it will naturally stretch</p>
      <p className="my5">open the height of the</p>
      <p className="my5">FlexEmbed.</p>
    </div>
  </FlexEmbed>
</div>

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

<div className="text-center">
    <ImageState
      src="https://via.placeholder.com/420x420"
      onComplete={() => console.log('loading complete')}
      onError={() => console.log('error')}
    >
      {({ completed, status, source, width }) => {
        if (status === 'failed' || status === 'empty') {
          return (
            <div
              className="bg-houseGreen"
              style={{
                border: 'red 3px solid',
                width: imgWidth,
                margin: 'auto'
              }}
            />
          );
        }
        if (status === 'loading') {
          return (
            <img
              src="https://via.placeholder.com/210"
              style={{ border: 'red 1px solid' }}
            />
          );
        }
        console.log(
          'When `status` === "completed", `completed` === true: ',
          completed
        );
        const imgWidth = width / 2;
        return (
          <img
            src={source}
            style={{
              border: 'blue 1px solid',
              width: imgWidth
            }}
          />
        );
      }}
    </ImageState>
    <p>To see error/failed, adjust ImageState src with an invalid image url</p>
  </div>

<div className="text-center">
    <ImageState
      src="https://via.placeholder.com/420x420"
      onComplete={() => console.log('loading complete')}
      onError={() => console.log('error')}
    >
      {({ completed, status, source, width }) => {
        if (status === 'failed' || status === 'empty') {
          return (
            <div
              className="bg-houseGreen"
              style={{
                border: 'red 3px solid',
                width: imgWidth,
                margin: 'auto'
              }}
            />
          );
        }
        if (status === 'loading') {
          return (
            <img
              src="https://via.placeholder.com/210"
              style={{ border: 'red 1px solid' }}
            />
          );
        }
        console.log(
          'When `status` === "completed", `completed` === true: ',
          completed
        );
        const imgWidth = width / 2;
        return (
          <img
            src={source}
            style={{
              border: 'blue 1px solid',
              width: imgWidth
            }}
          />
        );
      }}
    </ImageState>
    <p>To see error/failed, adjust ImageState src with an invalid image url</p>
  </div>