├── CONTRIBUTING.md
├── .storybook
    ├── addons.js
    ├── config.js
    └── webpack.config.js
├── src
    ├── index.tsx
    ├── fallbackUtils.tsx
    ├── LazyImage.tsx
    └── LazyImageFull.tsx
├── .prettier
├── tsconfig.json
├── stories
    ├── demo
    │   └── img
    │   │   ├── porto_buildings_large.jpg
    │   │   └── porto_buildings_lowres.jpg
    ├── utils.tsx
    ├── styles.css
    ├── LazyImageFull.story.tsx
    ├── OpinionatedComponents.tsx
    └── LazyImage.story.tsx
├── .gitignore
├── changes.md
├── .eslintrc
├── tsconfig_base.json
├── ROADMAP.md
├── FEEDBACK.md
├── LICENSE.md
├── package.json
└── README.md


/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/.storybook/addons.js:
--------------------------------------------------------------------------------
1 | import '@storybook/addon-options/register'
2 | import '@storybook/addon-actions/register'
3 | 


--------------------------------------------------------------------------------
/src/index.tsx:
--------------------------------------------------------------------------------
1 | export * from "./LazyImage";
2 | export * from "./LazyImageFull";
3 | // export * from './fallbackUtils';
4 | 


--------------------------------------------------------------------------------
/.prettier:
--------------------------------------------------------------------------------
1 | {
2 |   "printWidth": 80,
3 |   "bracketSpacing": false,
4 |   "singleQuote": true,
5 |   "trailingComma": "es5"
6 | }
7 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 |   "extends": "./tsconfig_base.json",
3 |   "compilerOptions": {
4 |     "declaration": false
5 |   }
6 | }
7 | 


--------------------------------------------------------------------------------
/stories/demo/img/porto_buildings_large.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/fpapado/react-lazy-images/HEAD/stories/demo/img/porto_buildings_large.jpg


--------------------------------------------------------------------------------
/stories/demo/img/porto_buildings_lowres.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/fpapado/react-lazy-images/HEAD/stories/demo/img/porto_buildings_lowres.jpg


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | .DS_Store
 2 | microbundle/
 3 | ts-build/
 4 | node_modules/
 5 | dist/
 6 | ts-build/
 7 | public/
 8 | cached/
 9 | app/
10 | npm-debug.log*
11 | .env
12 | .envrc
13 | .env.*
14 | *.swp
15 | .vscode/
16 | *.log
17 | .rpt2_cache/
18 | .out/
19 | 


--------------------------------------------------------------------------------
/changes.md:
--------------------------------------------------------------------------------
1 | - "Buffering" state is exposed in LazyImageFull, but not in LazyImage. Does it make sense to even expose?
2 |   - Not exposing it would be non-breaking!
3 | - Add "debounceDuration" or prop; decide on naming!
4 |   - Make optional, and 0 by default.
5 | 


--------------------------------------------------------------------------------
/.eslintrc:
--------------------------------------------------------------------------------
 1 | {
 2 |   "parser": "@typescript-eslint/parser",
 3 |   "plugins": [
 4 |     "jsx-a11y"
 5 |   ],
 6 |   "extends": [
 7 |     "plugin:jsx-a11y/recommended"
 8 |   ],
 9 |   "parserOptions": {
10 |     "ecmaVersion": 6,
11 |     "sourceType": "module",
12 |     "ecmaFeatures": {
13 |         "jsx": true
14 |     }
15 |   }
16 | }
17 | 


--------------------------------------------------------------------------------
/tsconfig_base.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "module": "es2015",
 4 |     "target": "es5",
 5 |     "declaration": true,
 6 |     "sourceMap": true,
 7 |     "jsx": "react",
 8 |     "allowJs": false,
 9 |     "strict": true,
10 |     "rootDirs": ["src", "stories"],
11 |     "outDir": "ts-build",
12 |     "moduleResolution": "node",
13 |     "allowSyntheticDefaultImports": true,
14 |     "esModuleInterop": true,
15 |     "lib": ["es6", "dom"],
16 |     "baseUrl": "./"
17 |   },
18 |   "include": ["src/**/*"],
19 |   "exclude": ["node_modules", "dist"]
20 | }
21 | 


--------------------------------------------------------------------------------
/.storybook/config.js:
--------------------------------------------------------------------------------
 1 | import React from 'react';
 2 | import {configure} from '@storybook/react';
 3 | import {setOptions} from '@storybook/addon-options';
 4 | import { setDefaults } from '@storybook/addon-info';
 5 | 
 6 | import 'tachyons';
 7 | 
 8 | // addon-info
 9 | setDefaults({
10 |   header: false, // Toggles display of header with component name and description
11 |   inline: true,
12 | });
13 | 
14 | setOptions({
15 |   name: 'React Lazy Images',
16 |   url: 'https://github.com/fpapado/react-lazy-images',
17 |   addonPanelInRight: true
18 | });
19 | 
20 | const req = require.context('../stories', true, /story\.tsx?$/)
21 | 
22 | function loadStories() {
23 |   req.keys().forEach(req)
24 | }
25 | 
26 | configure(loadStories, module)
27 | 


--------------------------------------------------------------------------------
/.storybook/webpack.config.js:
--------------------------------------------------------------------------------
 1 | const path = require('path');
 2 | // const TSDocgenPlugin = require('react-docgen-typescript-webpack-plugin');
 3 | 
 4 | module.exports = (baseConfig, env, config) => {
 5 |   config.module.rules.push({
 6 |     test: /\.tsx?$/,
 7 |     include: [
 8 |       path.resolve(__dirname, '../src/'),
 9 |       path.resolve(__dirname, '../stories/')
10 |     ],
11 |     use: [
12 |       require.resolve('awesome-typescript-loader'),
13 |       require.resolve('react-docgen-typescript-loader')
14 |     ],
15 |     exclude: [
16 |       path.resolve(__dirname, 'node_modules/'),
17 |     ]
18 |   });
19 |   // config.plugins.push(new TSDocgenPlugin());
20 |   config.resolve.extensions.push('.ts', '.tsx');
21 |   return config;
22 | };
23 | 


--------------------------------------------------------------------------------
/stories/utils.tsx:
--------------------------------------------------------------------------------
 1 | import React from "react";
 2 | 
 3 | export const Container: React.SFC<{}> = ({ children }) => (
 4 |   <div className="pa3 near-black bg-washed-yellow">
 5 |     <div
 6 |       className="flex justify-center items-center"
 7 |       style={{ minHeight: "calc(100vh + 100px)" }}
 8 |     >
 9 |       <p className="f3 sans-serif lh-copy measure-narrow">
10 |         Scroll down to see the photos :)<br />
11 |         You might want to throttle the network in your dev tools to see the
12 |         effect.
13 |       </p>
14 |     </div>
15 |     <div className="mw6">{children}</div>
16 |   </div>
17 | );
18 | 
19 | export const Divider: React.SFC<{}> = ({ children }) => (
20 |   <div style={{ minHeight: "calc(100vh + 100px)" }}>{children}</div>
21 | );
22 | 


--------------------------------------------------------------------------------
/ROADMAP.md:
--------------------------------------------------------------------------------
 1 | # Always
 2 | 
 3 | - Docs improvements! See [`FEEDBACK.md`](./FEEDBACK.md) for specific points.
 4 | - Loading patterns and auxiliary component examples
 5 | 
 6 | # v1
 7 | 
 8 | - [x] Upgrade devDeps
 9 | - [x] Upgrade microbundle
10 | - [x] Check --external all consequence
11 | - [x] Upgrade react-intersection-observer
12 | - [x] Pass Ref
13 | - [x] Prop collection
14 | - [x] Split out renderXYZ components
15 | - [x] Refactor props
16 | - [x] Elicit feedback and use cases for the public API
17 | - [~] Investigate container `<div>`
18 | - [ ] Solidify `<noscript>` fallback
19 | - [x] experimentalDecode
20 | 
21 | # Investigate
22 | 
23 | - [ ] Auto sizes (if not handled already by browser behaviour)
24 | - [ ] cancel loading on componentWillUnmount
25 | 
26 | # Later
27 | 
28 | - [ ] abort loading if image leaves viewport and it has not loaded sufficiently
29 |   - Likely a large change to how we do things
30 |   - Possibly with using fetch and cancelling it
31 |   - Probably a mess
32 | 


--------------------------------------------------------------------------------
/FEEDBACK.md:
--------------------------------------------------------------------------------
 1 | # Feedback
 2 | If you have input on any of these goals or questions (and anything along these lines), drop a line as a Github issue with the 'feedback' label.
 3 | I would be glad to discuss these with you.
 4 | 
 5 | ## Goals
 6 | In making this library, I had a number of design goals.
 7 | I think they offer valuable context for any input you might have.
 8 | 
 9 | - Keep the API surface minimal; provide configuration for the loading behaviour, but defer as much of the rendering as possible to the consumer
10 | - Make the state management in the components explicit and declarative
11 | - Provide auxiliary documentation for presentational patterns
12 | 
13 | ## Questions
14 | Here are some things I am wondering about that you might be able to help with:
15 | - Is the goal of the library apparent?
16 | - Do you think that the interface supports the goal of the library?
17 | - Were you able to figure out placeholder strategies? Are there things we could provide as examples?
18 | - Did you find the examples easy to navigate?
19 | 


--------------------------------------------------------------------------------
/src/fallbackUtils.tsx:
--------------------------------------------------------------------------------
 1 | import React from "react";
 2 | import { renderToStaticMarkup } from "react-dom/server";
 3 | 
 4 | /** Display this if JS is disabled
 5 |  * @see https://github.com/facebook/react/issues/11423 for why
 6 |  * this is here. Not ideal at all tbh.
 7 |  *
 8 |  * If you just use <noscript>, the browser will fetch the fallback directly.
 9 |  * There is really no common case where the <noscript> would be client-react-rendered
10 |  * (since JS would be disabled anyway), so this is fine to use on the server side.
11 |  *
12 |  * I would advise against using dangerouslySetInnerHTML,
13 |  * unless you trust the input, which is why we cannot offer this as the
14 |  * default in `LazyImage`. It will probably be more typing, and effort.
15 |  * Just decide what is best for your users and use case :)
16 |  *
17 |  * If the React <noscript> issue is fixed, then expect the library to offer
18 |  * a fallback API as it did in v0.3.0.
19 |  */
20 | 
21 | export const Fallback = (fallback: React.ReactElement<{}>) => (
22 |   <noscript>{renderToStaticMarkup(fallback)}</noscript>
23 | );
24 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2018 Fotis Papadogeorgopoulos
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/stories/styles.css:
--------------------------------------------------------------------------------
 1 | .bg-near-white {
 2 |   background-color: #f4f4f4;
 3 | }
 4 | 
 5 | .lh-copy {
 6 |   line-height: 1.5;
 7 | }
 8 | 
 9 | .sans-serif {
10 |   font-family: sans-serif;
11 | }
12 | 
13 | .intrinsic {
14 |   display: block;
15 | 
16 |   position: relative;
17 |   height: 0;
18 |   width: 100%;
19 | }
20 | 
21 | .intrinsic--square {
22 |   padding-top: 100%;
23 | }
24 | 
25 | .intrinsic--4x3 {
26 |   padding-top: 75%;
27 | }
28 | 
29 | .intrinsic--3x2 {
30 |   padding-top: 66.6%;
31 | }
32 | 
33 | .intrinsic-item {
34 |   position: absolute;
35 |   top: 0;
36 |   left: 0;
37 |   width: 100%;
38 |   height: 100%;
39 | }
40 | 
41 | .img {
42 |   max-width: 100%;
43 | }
44 | 
45 | .relative {
46 |   position: relative;
47 | }
48 | 
49 | .z-0 {
50 |   z-index: 0;
51 | }
52 | 
53 | .z-1 {
54 |   z-index: 1;
55 | }
56 | 
57 | .z-2 {
58 |   z-index: 2;
59 | }
60 | 
61 | /* Animations */
62 | .animated {
63 |   -webkit-animation-duration: 0.4s;
64 |   animation-duration: 0.4s;
65 |   -webkit-animation-fill-mode: both;
66 |   animation-fill-mode: both;
67 | }
68 | 
69 | @-webkit-keyframes fadeIn {
70 |   from {
71 |     opacity: 0;
72 |   }
73 | 
74 |   to {
75 |     opacity: 1;
76 |   }
77 | }
78 | 
79 | @keyframes fadeIn {
80 |   from {
81 |     opacity: 0;
82 |   }
83 | 
84 |   to {
85 |     opacity: 1;
86 |   }
87 | }
88 | 
89 | .fadeIn {
90 |   -webkit-animation-name: fadeIn;
91 |   animation-name: fadeIn;
92 | }
93 | 


--------------------------------------------------------------------------------
/stories/LazyImageFull.story.tsx:
--------------------------------------------------------------------------------
 1 | import React from "react";
 2 | import { storiesOf } from "@storybook/react";
 3 | import { action } from "@storybook/addon-actions";
 4 | import { withInfo } from "@storybook/addon-info";
 5 | import { LazyImageFull, ImageState } from "../src/index";
 6 | import { Container } from "./utils";
 7 | 
 8 | // Component that preloads the image and passes the loading state in render prop
 9 | //@ts-ignore
10 | const stories = storiesOf("LazyImageFull", module);
11 | 
12 | stories.add(
13 |   "Basic use",
14 |   withInfo(
15 |     `LazyImageFull gives you more fine-grained control over the rendering, by passing the state to the render prop.
16 |     Useful if you are doing css transitions, and where only some parts of the tree need to change.
17 |     Anything you can implement with LazyImage, you can implement with LazyImageFull.`
18 |   )(() => (
19 |     <Container>
20 |       <LazyImageFull
21 |         src="img/porto_buildings_large.jpg"
22 |         alt="Buildings with tiled exteriors, lit by the sunset."
23 |       >
24 |         {({ imageState, imageProps, ref }) => (
25 |           <img
26 |             {...imageProps}
27 |             ref={ref}
28 |             src={
29 |               imageState === ImageState.LoadSuccess
30 |                 ? imageProps.src
31 |                 : "img/porto_buildings_lowres.jpg"
32 |             }
33 |             className="w-100"
34 |           />
35 |         )}
36 |       </LazyImageFull>
37 |     </Container>
38 |   ))
39 | );
40 | 


--------------------------------------------------------------------------------
/stories/OpinionatedComponents.tsx:
--------------------------------------------------------------------------------
 1 | import React from "react";
 2 | import { LazyImage } from "../src/index";
 3 | 
 4 | /* Have you settled on how the actual images render in your application?
 5 |  * For instance, you might have a container and a class. You might have
 6 |  * tuned some options that match your use case, and just want to pass
 7 |  * the src.
 8 |  * Then you can easily abstract away to a level that works for you
 9 |  * and your team.
10 | */
11 | interface IOpinionated {
12 |   src: string;
13 |   alt: string;
14 | }
15 | 
16 | /** Component that shows a box as placeholder, fades the image in, and keeps the aspect ratio at 3x2
17 |  * This is probably not what you would name things, but it works for demonstration :)
18 |  */
19 | export const LazyImageOpinionated: React.SFC<IOpinionated> = ({ src, alt }) => (
20 |   <div className="bg-near-white intrinsic intrinsic--3x2">
21 |     <LazyImage
22 |       src={src}
23 |       alt={alt}
24 |       placeholder={({ ref }) => <div ref={ref} className="intrinsic-item" />}
25 |       actual={({ imageProps }) => (
26 |         <img {...imageProps} className="intrinsic-item animated fadeIn" />
27 |       )}
28 |       debounceDurationMs={1000}
29 |       debugActions={true}
30 |     />
31 |   </div>
32 | );
33 | 
34 | /** Component that shows an image as placeholder, fades the image in, and keeps the aspect ratio at 3x2
35 |  * Note that since we want the image to cross-fade on top of the placeholder one,
36 |  * we have to always show the placeholder.
37 |  * You could just as well toggle the placeholder/actual props to do this; it's mostly preference.
38 |  */
39 | export const LazyImageHoCWithPlaceholderSrc: React.SFC<
40 |   IOpinionated & { placeholderSrc: string }
41 | > = ({ src, alt, placeholderSrc }) => (
42 |   <div className="bg-near-white intrinsic intrinsic--3x2">
43 |     <img src={placeholderSrc} className="intrinsic-item" alt={alt} />
44 |     <LazyImage
45 |       src={src}
46 |       alt={alt}
47 |       placeholder={({ ref }) => <div ref={ref} className="intrinsic-item" />}
48 |       actual={({ imageProps }) => (
49 |         <img {...imageProps} className="intrinsic-item animated fadeIn" />
50 |       )}
51 |       debounceDurationMs={1000}
52 |     />
53 |   </div>
54 | );
55 | 


--------------------------------------------------------------------------------
/src/LazyImage.tsx:
--------------------------------------------------------------------------------
 1 | import React from "react";
 2 | import {
 3 |   LazyImageFull,
 4 |   CommonLazyImageProps,
 5 |   ImageState,
 6 |   ImageProps
 7 | } from "./LazyImageFull";
 8 | 
 9 | /**
10 |  * Valid props for LazyImage
11 |  */
12 | export interface LazyImageRenderPropArgs {
13 |   imageProps: ImageProps;
14 | }
15 | 
16 | export interface RefArg {
17 |   /** When not loading eagerly, a ref to bind to the DOM element. This is needed for the intersection calculation to work. */
18 |   ref?: React.RefObject<any> | ((node?: Element | null) => void);
19 | }
20 | 
21 | export interface LazyImageProps extends CommonLazyImageProps {
22 |   /** Component to display once image has loaded */
23 |   actual: (args: LazyImageRenderPropArgs) => React.ReactElement<{}>;
24 | 
25 |   /** Component to display while image has not been requested
26 |    * @default: undefined
27 |    */
28 |   placeholder: (
29 |     args: LazyImageRenderPropArgs & RefArg
30 |   ) => React.ReactElement<{}>;
31 | 
32 |   /** Component to display while the image is loading
33 |    * @default placeholder, if defined
34 |    */
35 |   loading?: () => React.ReactElement<{}>;
36 | 
37 |   /** Component to display if the image fails to load
38 |    * @default actual (broken image)
39 |    */
40 |   error?: () => React.ReactElement<{}>;
41 | }
42 | 
43 | /**
44 |  * Component that preloads the image once it is in the viewport,
45 |  * and then swaps it in. Has predefined rendering logic, but the
46 |  * specifics are up to the caller.
47 |  */
48 | export const LazyImage: React.FC<LazyImageProps> = ({
49 |   actual,
50 |   placeholder,
51 |   loading,
52 |   error,
53 |   ...rest
54 | }) => (
55 |   <LazyImageFull {...rest}>
56 |     {({ imageState, imageProps, ref }) => {
57 |       // Call the appropriate render callback based on the state
58 |       // and the props specified, passing on relevant props.
59 |       switch (imageState) {
60 |         case ImageState.NotAsked:
61 |           return !!placeholder && placeholder({ imageProps, ref });
62 | 
63 |         case ImageState.Loading:
64 |           // Only render loading if specified, otherwise placeholder
65 |           return !!loading
66 |             ? loading()
67 |             : !!placeholder && placeholder({ imageProps, ref });
68 | 
69 |         case ImageState.LoadSuccess:
70 |           return actual({ imageProps });
71 | 
72 |         case ImageState.LoadError:
73 |           // Only render error if specified, otherwise actual (broken image)
74 |           return !!error ? error() : actual({ imageProps });
75 |       }
76 |     }}
77 |   </LazyImageFull>
78 | );
79 | 
80 | LazyImage.displayName = "LazyImage";
81 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
  1 | {
  2 |   "name": "react-lazy-images",
  3 |   "description": "React utilities for lazy image loading",
  4 |   "version": "1.1.0",
  5 |   "source": "src/index.tsx",
  6 |   "module": "dist/react-lazy-images.es.js",
  7 |   "main": "dist/react-lazy-images.js",
  8 |   "umd:main": "dist/react-lazy-images.umd.js",
  9 |   "types": "dist/index.d.ts",
 10 |   "scripts": {
 11 |     "dev": "npm-run-all bundle:prod storybook",
 12 |     "dev:ts": "tsc --watch --pretty",
 13 |     "clean": "rimraf dist/",
 14 |     "build": "npm-run-all clean bundle:prod copy-defs size",
 15 |     "bundle:prod": "microbundle build",
 16 |     "bundle:watch": "microbundle watch",
 17 |     "copy-defs": "tsc --skipLibCheck && cp -r ts-build/*.d.ts dist/",
 18 |     "storybook": "start-storybook -p 8080",
 19 |     "storybook:build": "npm run bundle:prod && build-storybook -c .storybook -o .out",
 20 |     "storybook:deploy": "storybook-to-ghpages --existing-output-dir=.out",
 21 |     "test": "npm run build",
 22 |     "size": "bundlesize",
 23 |     "release": "npm t && git commit -am $npm_package_version && git tag $npm_package_version && git push && git push --tags && npm publish"
 24 |   },
 25 |   "bundlesize": [
 26 |     {
 27 |       "path": "dist/react-lazy-images.js",
 28 |       "maxSize": "3kb"
 29 |     }
 30 |   ],
 31 |   "husky": {
 32 |     "hooks": {
 33 |       "pre-commit": "lint-staged"
 34 |     }
 35 |   },
 36 |   "lint-staged": {
 37 |     "*.{js,ts,tsx}": [
 38 |       "eslint",
 39 |       "git add"
 40 |     ],
 41 |     "*.{js,ts,tsx,json,css,md}": [
 42 |       "prettier --write",
 43 |       "git add"
 44 |     ]
 45 |   },
 46 |   "files": [
 47 |     "src",
 48 |     "dist"
 49 |   ],
 50 |   "keywords": [
 51 |     "react",
 52 |     "lazy",
 53 |     "image",
 54 |     "intersection",
 55 |     "viewport"
 56 |   ],
 57 |   "repository": {
 58 |     "type": "git",
 59 |     "url": "git+https://github.com/fpapado/react-lazy-images.git"
 60 |   },
 61 |   "author": "Fotis Papadogeorgopoulos",
 62 |   "license": "MIT",
 63 |   "bugs": {
 64 |     "url": "https://github.com/fpapado/react-lazy-images/issues"
 65 |   },
 66 |   "homepage": "https://github.com/fpapado/react-lazy-images#readme",
 67 |   "dependencies": {
 68 |     "react-intersection-observer": "^9.4.0",
 69 |     "unionize": "^2.1.2"
 70 |   },
 71 |   "peerDependencies": {
 72 |     "react": "^15 || ^16 || ^17 || ^18",
 73 |     "react-dom": "^15 || ^16 || ^17 || ^18"
 74 |   },
 75 |   "devDependencies": {
 76 |     "@storybook/addon-actions": "4.0.0-alpha.14",
 77 |     "@storybook/addon-info": "4.0.0-alpha.14",
 78 |     "@storybook/addon-options": "4.0.0-alpha.14",
 79 |     "@storybook/addons": "4.0.0-alpha.14",
 80 |     "@storybook/react": "4.0.0-alpha.14",
 81 |     "@storybook/storybook-deployer": "^2.3.0",
 82 |     "@types/react": "^18.0.18",
 83 |     "@types/react-dom": "^18.0.6",
 84 |     "@types/storybook__addon-actions": "^3.0.3",
 85 |     "@types/storybook__addon-info": "^3.2.3",
 86 |     "@types/storybook__react": "^3.0.8",
 87 |     "@typescript-eslint/parser": "^5.36.2",
 88 |     "awesome-typescript-loader": "^5.2",
 89 |     "babel-core": "^6.26.3",
 90 |     "bundlesize": "^0.18.1",
 91 |     "eslint": "^5.1.0",
 92 |     "eslint-plugin-jsx-a11y": "^6.1.1",
 93 |     "husky": "^1.0.0-rc.13",
 94 |     "lint-staged": "^7.2.0",
 95 |     "microbundle": "0.5.1",
 96 |     "npm-run-all": "^4.1.3",
 97 |     "prettier": "^1.13.7",
 98 |     "react": "^18.2.0",
 99 |     "react-docgen-typescript": "^1.6.2",
100 |     "react-docgen-typescript-loader": "^2.1.1",
101 |     "react-docgen-typescript-webpack-plugin": "^1.1.0",
102 |     "react-dom": "^18.2.0",
103 |     "require-from-string": "^2.0.2",
104 |     "tachyons": "^4.10.0",
105 |     "typescript": "^4.8.2"
106 |   }
107 | }
108 | 


--------------------------------------------------------------------------------
/stories/LazyImage.story.tsx:
--------------------------------------------------------------------------------
  1 | import React from "react";
  2 | import { storiesOf } from "@storybook/react";
  3 | import { action } from "@storybook/addon-actions";
  4 | import { withInfo } from "@storybook/addon-info";
  5 | import { LazyImage } from "../src/index";
  6 | import { Container, Divider } from "./utils";
  7 | import { LazyImageOpinionated } from "./OpinionatedComponents";
  8 | import "./styles.css";
  9 | 
 10 | // Helpers to save typing. You can imagine that in
 11 | // some cases, you too will have more specific components.
 12 | const PlaceholderImage = () => (
 13 |   <img
 14 |     src="img/porto_buildings_lowres.jpg"
 15 |     alt="Buildings with tiled exteriors, lit by the sunset."
 16 |     className="w-100"
 17 |   />
 18 | );
 19 | 
 20 | const ActualImage = () => (
 21 |   <img
 22 |     src="img/porto_buildings_large.jpg"
 23 |     alt="Buildings with tiled exteriors, lit by the sunset."
 24 |     className="w-100"
 25 |   />
 26 | );
 27 | 
 28 | // Utils for scrolling
 29 | const scrollToRef = (ref: React.RefObject<any>) =>
 30 |   ref.current.scrollIntoView({ behavior: "smooth" });
 31 | const endRef: React.RefObject<any> = React.createRef();
 32 | 
 33 | // Component that preloads the image and only swaps once ready
 34 | //@ts-ignore
 35 | const stories = storiesOf("LazyImage", module);
 36 | 
 37 | stories
 38 |   .add(
 39 |     "Basic use",
 40 |     withInfo(
 41 |       "Component that preloads the image once in the viewport and only swaps once ready"
 42 |     )(() => (
 43 |       <Container>
 44 |         <LazyImage
 45 |           src="img/porto_buildings_large.jpg"
 46 |           alt="Buildings with tiled exteriors, lit by the sunset."
 47 |           placeholder={({ imageProps, ref }) => (
 48 |             <img
 49 |               ref={ref}
 50 |               src="img/porto_buildings_lowres.jpg"
 51 |               alt={imageProps.alt}
 52 |               className="w-100"
 53 |             />
 54 |           )}
 55 |           actual={({ imageProps }) => <img {...imageProps} className="w-100" />}
 56 |         />
 57 |       </Container>
 58 |     ))
 59 |   )
 60 |   // With srcSet
 61 |   .add(
 62 |     "With srcSet",
 63 |     withInfo(
 64 |       "With srcset, the browser decides which image to load. In that case, src is not informative enough for preloading. You can use the `srcSet` prop to provide that additional information to LazyImage."
 65 |     )(() => (
 66 |       <Container>
 67 |         <LazyImage
 68 |           src="https://www.fillmurray.com/g/300/200"
 69 |           srcSet="https://www.fillmurray.com/g/900/600 900w, https://www.fillmurray.com/g/600/400 600w, https://www.fillmurray.com/g/300/200 300w"
 70 |           alt="A portrait of Bill Murray."
 71 |           placeholder={({ imageProps, ref }) => (
 72 |             <img
 73 |               ref={ref}
 74 |               src="https://www.fillmurray.com/g/60/40"
 75 |               alt={imageProps.alt}
 76 |               className="w-100"
 77 |             />
 78 |           )}
 79 |           actual={({ imageProps }) => <img {...imageProps} className="w-100" />}
 80 |         />
 81 |       </Container>
 82 |     ))
 83 |   )
 84 |   // Always load an image ("eagerly"; how the browser does it already.
 85 |   // Useful if you want to load the actual content without waiting for Javascript.
 86 |   .add(
 87 |     "Eager loading (Server-Side Rendering)",
 88 |     withInfo(
 89 |       "Always load an image (i.e. eagerly; how the browser does it already). Useful if you want to load the actual content without waiting for Javascript. You should consider where you need this pattern. See the relevant section in README.md for more."
 90 |     )(() => (
 91 |       <Container>
 92 |         <LazyImage
 93 |           loadEagerly
 94 |           src="img/porto_buildings_large.jpg"
 95 |           placeholder={() => <PlaceholderImage />}
 96 |           actual={() => <ActualImage />}
 97 |         />
 98 |       </Container>
 99 |     ))
100 |   )
101 |   // This isn't even specific to this library; just demonstrating how you might
102 |   // eagerly load content above the fold, and defer the rest
103 |   .add(
104 |     "Eagerly load some images",
105 |     withInfo(
106 |       "This is an example of how you can use loadEagerly to load important content directly, and defer the rest."
107 |     )(() => (
108 |       <Container>
109 |         {[
110 |           ["first", "30/20", "300/200"],
111 |           ["second", "60/40", "600/400"],
112 |           ["third", "90/60", "900/600"]
113 |         ].map(([key, placeholder, actual], i) => (
114 |           <LazyImage
115 |             loadEagerly={i === 0}
116 |             key={key}
117 |             src={`https://www.fillmurray.com/g/${actual}`}
118 |             alt="A portrait of Bill Murray."
119 |             placeholder={({ imageProps, ref }) => (
120 |               <img
121 |                 src={`https://www.fillmurray.com/g/${placeholder}`}
122 |                 ref={ref}
123 |                 alt={imageProps.alt}
124 |                 className="w-100"
125 |               />
126 |             )}
127 |             actual={({ imageProps }) => (
128 |               <img {...imageProps} className="w-100" />
129 |             )}
130 |           />
131 |         ))}
132 |       </Container>
133 |     ))
134 |   )
135 |   .add(
136 |     "Delayed loading",
137 |     withInfo(
138 |       "By specifying `debounceDurationMs`, you can prevent an image from loading, unless it has been in the viewport for a set amount of time."
139 |     )(() => {
140 |       return (
141 |         <div className="mw6">
142 |           <Divider>
143 |             <h1>react-lazy-images Debounce test</h1>
144 |             <p>
145 |               The desired behaviour is to not to start loading the images before
146 |               them being in the viewport for X amount of time. Press the button
147 |               to scroll alll the way to the end of the page. Only the final
148 |               image should be loaded.
149 |             </p>
150 |             <p>
151 |               Open your devTools network monitor and check the "Img" tab. Only
152 |               the last image should load.
153 |             </p>
154 |             <p>
155 |               (Note that smooth scrolling should be working in your browser for
156 |               the test to be realistic. If not, you can scroll manually. Instant
157 |               scrolling does not trigger the IntersectionObserver afaict).
158 |             </p>
159 |             <button onClick={() => scrollToRef(endRef)}>
160 |               Click here to scroll to the end
161 |             </button>
162 |           </Divider>
163 | 
164 |           <LazyImageOpinionated
165 |             src="https://endangered.photo/1200/800"
166 |             alt=""
167 |           />
168 | 
169 |           <Divider />
170 | 
171 |           <h2 ref={endRef}>Only things below here should be loaded</h2>
172 |           <LazyImageOpinionated src="https://endangered.photo/300/200" alt="" />
173 |         </div>
174 |       );
175 |     })
176 |   )
177 |   // Loading state as render prop
178 |   .add(
179 |     "Loading state",
180 |     withInfo("Loading")(() => (
181 |       <Container>
182 |         <div className="bg-light-silver h5 w-100">
183 |           <LazyImage
184 |             src="img/porto_buildings_large.jpg"
185 |             placeholder={({ ref }) => <div ref={ref} />}
186 |             actual={() => <ActualImage />}
187 |             loading={() => (
188 |               <div>
189 |                 <p className="pa3 f5 lh-copy near-white">Loading...</p>
190 |               </div>
191 |             )}
192 |           />
193 |         </div>
194 |       </Container>
195 |     ))
196 |   )
197 |   // Loading and Error states as render props
198 |   .add(
199 |     "Loading and Error states",
200 |     withInfo("Loading and Error states are exposed as render props")(() => (
201 |       <Container>
202 |         <div className="bg-light-silver h5 w-100">
203 |           <LazyImage
204 |             src="https://www.fillmurray.com/notanimage"
205 |             placeholder={({ ref }) => <div ref={ref} />}
206 |             actual={({ imageProps }) => <img {...imageProps} />}
207 |             loading={() => (
208 |               <div>
209 |                 <p className="pa3 f5 lh-copy near-white">Loading...</p>
210 |               </div>
211 |             )}
212 |             error={() => (
213 |               <div className={`bg-light-red h-100 w-100 $`}>
214 |                 <p>There was an error fetching this image :(</p>
215 |               </div>
216 |             )}
217 |           />
218 |         </div>
219 |       </Container>
220 |     ))
221 |   )
222 |   .add(
223 |     "Horizontal scroll",
224 |     withInfo("Horizontal scrolling should work out of the box.")(() => (
225 |       <Container>
226 |         <div className="flex flex-row mw6 overflow-x-auto">
227 |           {[
228 |             ["first", "30/20", "300/200"],
229 |             ["second", "60/40", "600/400"],
230 |             ["third", "90/60", "900/600"]
231 |           ].map(([key, placeholder, actual], i) => (
232 |             <div
233 |               key={key}
234 |               className="w5 pa3 mr3 ba bw1 b--near-black flex-shrink-0"
235 |             >
236 |               <LazyImage
237 |                 key={key}
238 |                 src={`https://www.fillmurray.com/g/${actual}`}
239 |                 alt="A portrait of Bill Murray."
240 |                 placeholder={({ imageProps, ref }) => (
241 |                   <img
242 |                     src={`https://www.fillmurray.com/g/${placeholder}`}
243 |                     ref={ref}
244 |                     alt={imageProps.alt}
245 |                     className="w-100"
246 |                   />
247 |                 )}
248 |                 actual={({ imageProps }) => (
249 |                   <img {...imageProps} className="w-100" />
250 |                 )}
251 |               />
252 |             </div>
253 |           ))}
254 |         </div>
255 |       </Container>
256 |     ))
257 |   )
258 |   .add(
259 |     "Experimental decode",
260 |     withInfo(
261 |       "Decode off-main-thread before appending. Only supported in some browsers, but uses normal API otherwise. Test before using!"
262 |     )(() => (
263 |       <Container>
264 |         <LazyImage
265 |           src="img/porto_buildings_large.jpg"
266 |           alt="Buildings with tiled exteriors, lit by the sunset."
267 |           placeholder={({ imageProps, ref }) => (
268 |             <img
269 |               ref={ref}
270 |               src="img/porto_buildings_lowres.jpg"
271 |               alt={imageProps.alt}
272 |               className="w-100"
273 |             />
274 |           )}
275 |           actual={({ imageProps }) => <img {...imageProps} className="w-100" />}
276 |           experimentalDecode={true}
277 |         />
278 |       </Container>
279 |     ))
280 |   )
281 |   .add(
282 |     "Background image",
283 |     withInfo(
284 |       "You are in control of what gets rendered, so you can set the url of the background image, and swap in a component that uses it on load. It is not much different from the basic use case."
285 |     )(() => {
286 |       return (
287 |         <Container>
288 |           <LazyImage
289 |             src="img/porto_buildings_large.jpg"
290 |             placeholder={({ ref }) => (
291 |               <div
292 |                 ref={ref}
293 |                 className={`$ w5 h5 contain bg-center`}
294 |                 style={{
295 |                   backgroundImage: "url(img/porto_buildings_lowres.jpg)"
296 |                 }}
297 |               />
298 |             )}
299 |             actual={({ imageProps }) => (
300 |               <div
301 |                 className={`$ w5 h5 contain bg-center`}
302 |                 style={{
303 |                   backgroundImage: `url(${imageProps.src})`
304 |                 }}
305 |               />
306 |             )}
307 |           />
308 |         </Container>
309 |       );
310 |     })
311 |   );
312 | 


--------------------------------------------------------------------------------
/src/LazyImageFull.tsx:
--------------------------------------------------------------------------------
  1 | import React from "react";
  2 | import { InView } from "react-intersection-observer";
  3 | import { unionize, ofType, UnionOf } from "unionize";
  4 | 
  5 | /**
  6 |  * Valid props for LazyImage components
  7 |  */
  8 | export type CommonLazyImageProps = ImageProps & {
  9 |   // NOTE: if you add props here, remember to destructure them out of being
 10 |   // passed to the children, in the render() callback.
 11 | 
 12 |   /** Whether to skip checking for viewport and always show the 'actual' component
 13 |    * @see https://github.com/fpapado/react-lazy-images/#eager-loading--server-side-rendering-ssr
 14 |    */
 15 |   loadEagerly?: boolean;
 16 | 
 17 |   /** Subset of props for the IntersectionObserver
 18 |    * @see https://github.com/thebuilder/react-intersection-observer#props
 19 |    */
 20 |   observerProps?: ObserverProps;
 21 | 
 22 |   /** Use the Image Decode API;
 23 |    * The call to a new HTML <img> element’s decode() function returns a promise, which,
 24 |    * when fulfilled, ensures that the image can be appended to the DOM without causing
 25 |    * a decoding delay on the next frame.
 26 |    *  @see: https://www.chromestatus.com/feature/5637156160667648
 27 |    */
 28 |   experimentalDecode?: boolean;
 29 | 
 30 |   /** Whether to log out internal state transitions for the component */
 31 |   debugActions?: boolean;
 32 | 
 33 |   /** Delay a certain duration before starting to load, in ms.
 34 |    * This can help avoid loading images while the user scrolls quickly past them.
 35 |    * TODO: naming things.
 36 |    */
 37 |   debounceDurationMs?: number;
 38 | };
 39 | 
 40 | /** Valid props for LazyImageFull */
 41 | export interface LazyImageFullProps extends CommonLazyImageProps {
 42 |   /** Children should be either a function or a node */
 43 |   children: (args: RenderCallbackArgs) => React.ReactNode;
 44 | }
 45 | 
 46 | /** Values that the render props take */
 47 | export interface RenderCallbackArgs {
 48 |   imageState: ImageState;
 49 |   imageProps: ImageProps;
 50 |   /** When not loading eagerly, a ref to bind to the DOM element. This is needed for the intersection calculation to work. */
 51 |   ref?: React.RefObject<any> | ((node?: Element | null) => void);
 52 | }
 53 | 
 54 | export interface ImageProps {
 55 |   /** The source of the image to load */
 56 |   src: string;
 57 | 
 58 |   /** The source set of the image to load */
 59 |   srcSet?: string;
 60 | 
 61 |   /** The alt text description of the image you are loading */
 62 |   alt?: string;
 63 | 
 64 |   /** Sizes descriptor */
 65 |   sizes?: string;
 66 | }
 67 | 
 68 | /** Subset of react-intersection-observer's props */
 69 | export interface ObserverProps {
 70 |   /**
 71 |    * Margin around the root that expands the area for intersection.
 72 |    * @see https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin
 73 |    * @default "50px 0px"
 74 |    * @example Declaration same as CSS margin:
 75 |    *  `"10px 20px 30px 40px"` (top, right, bottom, left).
 76 |    */
 77 |   rootMargin?: string;
 78 | 
 79 |   /** Number between 0 and 1 indicating the the percentage that should be
 80 |    * visible before triggering.
 81 |    * @default `0.01`
 82 |    */
 83 |   threshold?: number;
 84 | }
 85 | 
 86 | /** States that the image loading can be in.
 87 |  * Used together with LazyImageFull render props.
 88 |  * External representation of the internal state.
 89 |  * */
 90 | export enum ImageState {
 91 |   NotAsked = "NotAsked",
 92 |   Loading = "Loading",
 93 |   LoadSuccess = "LoadSuccess",
 94 |   LoadError = "LoadError"
 95 | }
 96 | 
 97 | /** The component's state */
 98 | const LazyImageFullState = unionize({
 99 |   NotAsked: {},
100 |   Buffering: {},
101 |   // Could try to make it Promise<HTMLImageElement>,
102 |   // but we don't use the element anyway, and we cache promises
103 |   Loading: {},
104 |   LoadSuccess: {},
105 |   LoadError: ofType<{ msg: string }>()
106 | });
107 | 
108 | type LazyImageFullState = UnionOf<typeof LazyImageFullState>;
109 | 
110 | /** Actions that change the component's state.
111 |  * These are not unlike Actions in Redux or, the ones I'm inspired by,
112 |  * Msg in Elm.
113 |  */
114 | const Action = unionize({
115 |   ViewChanged: ofType<{ inView: boolean }>(),
116 |   BufferingEnded: {},
117 |   // MAYBE: Load: {},
118 |   LoadSuccess: {},
119 |   LoadError: ofType<{ msg: string }>()
120 | });
121 | 
122 | type Action = UnionOf<typeof Action>;
123 | 
124 | /** Commands (Cmd) describe side-effects as functions that take the instance */
125 | // FUTURE: These should be tied to giving back a Msg / asynchronoulsy giving a Msg with conditions
126 | type Cmd = (instance: LazyImageFull) => void;
127 | 
128 | /** The output from a reducer is the next state and maybe a command */
129 | type ReducerResult = {
130 |   nextState: LazyImageFullState;
131 |   cmd?: Cmd;
132 | };
133 | 
134 | ///// Commands, things that perform side-effects /////
135 | /** Get a command that sets a buffering Promise */
136 | const getBufferingCmd = (durationMs: number): Cmd => instance => {
137 |   // Make cancelable buffering Promise
138 |   const bufferingPromise = makeCancelable(delayedPromise(durationMs));
139 | 
140 |   // Kick off promise chain
141 |   bufferingPromise.promise
142 |     .then(() => instance.update(Action.BufferingEnded()))
143 |     .catch(
144 |       _reason => {}
145 |       //console.log({ isCanceled: _reason.isCanceled })
146 |     );
147 | 
148 |   // Side-effect; set the promise in the cache
149 |   instance.promiseCache.buffering = bufferingPromise;
150 | };
151 | 
152 | /** Get a command that sets an image loading Promise */
153 | const getLoadingCmd = (
154 |   imageProps: ImageProps,
155 |   experimentalDecode?: boolean
156 | ): Cmd => instance => {
157 |   // Make cancelable loading Promise
158 |   const loadingPromise = makeCancelable(
159 |     loadImage(imageProps, experimentalDecode)
160 |   );
161 | 
162 |   // Kick off request for Image and attach listeners for response
163 |   loadingPromise.promise
164 |     .then(_res => instance.update(Action.LoadSuccess({})))
165 |     .catch(e => {
166 |       // If the Loading Promise was canceled, it means we have stopped
167 |       // loading due to unmount, rather than an error.
168 |       if (!e.isCanceled) {
169 |         // TODO: think more about the error here
170 |         instance.update(Action.LoadError({ msg: "Failed to load" }));
171 |       }
172 |     });
173 | 
174 |   // Side-effect; set the promise in the cache
175 |   instance.promiseCache.loading = loadingPromise;
176 | };
177 | 
178 | /** Command that cancels the buffering Promise */
179 | const cancelBufferingCmd: Cmd = instance => {
180 |   // Side-effect; cancel the promise in the cache
181 |   // We know this exists if we are in a Buffering state
182 |   instance.promiseCache.buffering.cancel();
183 | };
184 | 
185 | /**
186 |  * Component that preloads the image once it is in the viewport,
187 |  * and then swaps it in. Takes a render prop that allows to specify
188 |  * what is rendered based on the loading state.
189 |  */
190 | export class LazyImageFull extends React.Component<
191 |   LazyImageFullProps,
192 |   LazyImageFullState
193 | > {
194 |   static displayName = "LazyImageFull";
195 | 
196 |   /** A central place to store promises.
197 |    * A bit silly, but passing promises directly in the state
198 |    * was giving me weird timing issues. This way we can keep
199 |    * the promises in check, and pick them up from the respective methods.
200 |    * FUTURE: Could pass the relevant key in Buffering and Loading, so
201 |    * that at least we know where they are from a single source.
202 |    */
203 |   promiseCache: {
204 |     [key: string]: CancelablePromise;
205 |   } = {};
206 | 
207 |   initialState = LazyImageFullState.NotAsked();
208 | 
209 |   /** Emit the next state based on actions.
210 |    *  This is the core of the component!
211 |    */
212 |   static reducer(
213 |     action: Action,
214 |     prevState: LazyImageFullState,
215 |     props: LazyImageFullProps
216 |   ): ReducerResult {
217 |     return Action.match(action, {
218 |       ViewChanged: ({ inView }) => {
219 |         if (inView === true) {
220 |           // If src is not specified, then there is nothing to preload; skip to Loaded state
221 |           if (!props.src) {
222 |             return { nextState: LazyImageFullState.LoadSuccess() }; // Error wtf
223 |           } else {
224 |             // If in view, only load something if NotAsked, otherwise leave untouched
225 |             return LazyImageFullState.match(prevState, {
226 |               NotAsked: () => {
227 |                 // If debounce is specified, then start buffering
228 |                 if (!!props.debounceDurationMs) {
229 |                   return {
230 |                     nextState: LazyImageFullState.Buffering(),
231 |                     cmd: getBufferingCmd(props.debounceDurationMs)
232 |                   };
233 |                 } else {
234 |                   // If no debounce is specified, then start loading immediately
235 |                   return {
236 |                     nextState: LazyImageFullState.Loading(),
237 |                     cmd: getLoadingCmd(props, props.experimentalDecode)
238 |                   };
239 |                 }
240 |               },
241 |               // Do nothing in other states
242 |               default: () => ({ nextState: prevState })
243 |             });
244 |           }
245 |         } else {
246 |           // If out of view, cancel if Buffering, otherwise leave untouched
247 |           return LazyImageFullState.match(prevState, {
248 |             Buffering: () => ({
249 |               nextState: LazyImageFullState.NotAsked(),
250 |               cmd: cancelBufferingCmd
251 |             }),
252 |             // Do nothing in other states
253 |             default: () => ({ nextState: prevState })
254 |           });
255 |         }
256 |       },
257 |       // Buffering has ended/succeeded, kick off request for image
258 |       BufferingEnded: () => ({
259 |         nextState: LazyImageFullState.Loading(),
260 |         cmd: getLoadingCmd(props, props.experimentalDecode)
261 |       }),
262 |       // Loading the image succeeded, simple
263 |       LoadSuccess: () => ({ nextState: LazyImageFullState.LoadSuccess() }),
264 |       // Loading the image failed, simple
265 |       LoadError: e => ({ nextState: LazyImageFullState.LoadError(e) })
266 |     });
267 |   }
268 | 
269 |   constructor(props: LazyImageFullProps) {
270 |     super(props);
271 |     this.state = this.initialState;
272 | 
273 |     // Bind methods
274 |     this.update = this.update.bind(this);
275 |   }
276 | 
277 |   update(action: Action) {
278 |     // Get the next state and any effects
279 |     const { nextState, cmd } = LazyImageFull.reducer(
280 |       action,
281 |       this.state,
282 |       this.props
283 |     );
284 | 
285 |     // Debugging
286 |     if (this.props.debugActions) {
287 |       if (process.env.NODE_ENV === "production") {
288 |         console.warn(
289 |           'You are running LazyImage with debugActions="true" in production. This might have performance implications.'
290 |         );
291 |       }
292 |       console.log({ action, prevState: this.state, nextState });
293 |     }
294 | 
295 |     // Actually set the state, and kick off any effects after that
296 |     this.setState(nextState, () => cmd && cmd(this));
297 |   }
298 | 
299 |   componentWillUnmount() {
300 |     // Clear the Promise Cache
301 |     if (this.promiseCache.loading) {
302 |       // NOTE: This does not cancel the request, only the callback.
303 |       // We we would need fetch() and an AbortHandler for that.
304 |       this.promiseCache.loading.cancel();
305 |     }
306 |     if (this.promiseCache.buffering) {
307 |       this.promiseCache.buffering.cancel();
308 |     }
309 |     this.promiseCache = {};
310 |   }
311 | 
312 |   // Render function
313 |   render() {
314 |     // This destructuring is silly
315 |     const {
316 |       children,
317 |       loadEagerly,
318 |       observerProps,
319 |       experimentalDecode,
320 |       debounceDurationMs,
321 |       debugActions,
322 |       ...imageProps
323 |     } = this.props;
324 | 
325 |     if (loadEagerly) {
326 |       // If eager, skip the observer and view changing stuff; resolve the imageState as loaded.
327 |       return children({
328 |         // We know that the state tags and the enum match up
329 |         imageState: LazyImageFullState.LoadSuccess().tag as ImageState,
330 |         imageProps
331 |       });
332 |     } else {
333 |       return (
334 |         <InView
335 |           rootMargin="50px 0px"
336 |           // TODO: reconsider threshold
337 |           threshold={0.01}
338 |           {...observerProps}
339 |           onChange={(inView: boolean) =>
340 |             this.update(Action.ViewChanged({ inView }))
341 |           }
342 |         >
343 |           {({ ref }: RenderProps) =>
344 |             children({
345 |               // We know that the state tags and the enum match up, apart
346 |               // from Buffering not being exposed
347 |               imageState:
348 |                 this.state.tag === "Buffering"
349 |                   ? ImageState.Loading
350 |                   : (this.state.tag as ImageState),
351 |               imageProps,
352 |               ref
353 |             })
354 |           }
355 |         </InView>
356 |       );
357 |     }
358 |   }
359 | }
360 | 
361 | interface RenderProps {
362 |   inView: boolean;
363 |   entry: IntersectionObserverEntry | undefined;
364 |   ref: React.RefObject<any> | ((node?: Element | null) => void);
365 | }
366 | 
367 | ///// Utilities /////
368 | 
369 | /** Promise constructor for loading an image */
370 | const loadImage = (
371 |   { src, srcSet, alt, sizes }: ImageProps,
372 |   experimentalDecode = false
373 | ) =>
374 |   new Promise((resolve, reject) => {
375 |     const image = new Image();
376 |     if (srcSet) {
377 |       image.srcset = srcSet;
378 |     }
379 |     if (alt) {
380 |       image.alt = alt;
381 |     }
382 |     if (sizes) {
383 |       image.sizes = sizes;
384 |     }
385 |     image.src = src;
386 | 
387 |     /** @see: https://www.chromestatus.com/feature/5637156160667648 */
388 |     if (experimentalDecode && "decode" in image) {
389 |       return (
390 |         image
391 |           // NOTE: .decode() is not in the TS defs yet
392 |           // TODO: consider writing the .decode() definition and sending a PR
393 |           //@ts-ignore
394 |           .decode()
395 |           .then(() => resolve(image))
396 |           .catch((err: any) => reject(err))
397 |       );
398 |     }
399 | 
400 |     image.onload = resolve;
401 |     image.onerror = reject;
402 |   });
403 | 
404 | /** Promise that resolves after a specified number of ms */
405 | const delayedPromise = (ms: number) =>
406 |   new Promise(resolve => setTimeout(resolve, ms));
407 | 
408 | interface CancelablePromise {
409 |   promise: Promise<any>;
410 |   cancel: () => void;
411 | }
412 | 
413 | /** Make a Promise "cancelable".
414 |  *
415 |  * Rejects with {isCanceled: true} if canceled.
416 |  *
417 |  * The way this works is by wrapping it with internal hasCanceled_ state
418 |  * and checking it before resolving.
419 |  */
420 | const makeCancelable = (promise: Promise<any>): CancelablePromise => {
421 |   let hasCanceled_ = false;
422 | 
423 |   const wrappedPromise: Promise<any> = new Promise((resolve, reject) => {
424 |     promise.then(
425 |       (val: any) => (hasCanceled_ ? reject({ isCanceled: true }) : resolve(val))
426 |     );
427 |     promise.catch(
428 |       (error: any) =>
429 |         hasCanceled_ ? reject({ isCanceled: true }) : reject(error)
430 |     );
431 |   });
432 | 
433 |   return {
434 |     promise: wrappedPromise,
435 |     cancel() {
436 |       hasCanceled_ = true;
437 |     }
438 |   };
439 | };
440 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # React Lazy Images
  2 | 
  3 | > Components and utilities for lazy image loading in React.
  4 | 
  5 | [![npm](https://img.shields.io/npm/v/react-lazy-images.svg)](https://www.npmjs.com/package/react-lazy-images)
  6 | [![gzip size](http://img.badgesize.io/https://unpkg.com/react-lazy-images/dist/react-lazy-images.js?compression=gzip)](https://unpkg.com/react-lazy-images/dist/react-lazy-images.js)
  7 | [![npm downloads](https://img.shields.io/npm/dm/react-lazy-images.svg)](https://www.npmjs.com/package/react-lazy-images)
  8 | [![dependencies](https://david-dm.org/fpapado/react-lazy-images.svg)](https://david-dm.org/fpapado/react-lazy-images)
  9 | <a href="https://codesandbox.io/s/jnn9wjkj1w">
 10 | <img src="https://codesandbox.io/static/img/play-codesandbox.svg" height="20px"/>
 11 | </a>
 12 | 
 13 | ## Table of Contents
 14 | 
 15 | - [Features](#features)
 16 | - [Install](#install)
 17 | - [Motivation](#motivation)
 18 | - [Usage](#usage)
 19 | - [Examples](#examples)
 20 | - [API Reference](#api-reference)
 21 | - [Feedback](#feedback)
 22 | - [Roadmap](#roadmap)
 23 | - [Contributing](#contributing)
 24 | - [Thanks](#thanks-and-inspiration)
 25 | - [License](#license)
 26 | 
 27 | ## Features
 28 | 
 29 | - Composable pieces, preloading images and handling failures.
 30 | - Full presentational control for the caller (render props).
 31 | - Modern, performant implementation, using [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) and providing [polyfill information](#polyfill-intersection-observer).
 32 | - [Eager loading / Server-side rendering support](#eager-loading--server-side-rendering-ssr).
 33 | - [Debounce / Delay](#debounce--delay); can wait for an image to be in the viewport for a set time, before loading.
 34 | - Works with horizontal scrolling, supports background images.
 35 | - [Fallbacks for SEO / when Javascript is disabled](#fallback-without-javascript).
 36 | - Easy to understand source code. You should be able to fork and do your thing if desired.
 37 | - Ample documentation to help you understand the problem, in addition to the solutions.
 38 | 
 39 | What it does not do by itself:
 40 | 
 41 | - Polyfill `IntersectionObserver`. Adding polyfills is something you should do consciously at the application level. See [Polyfilling IntersectionObserver](#polyfill-intersectionobserver) for how to do this.
 42 | - Dictate the kind of placeholders displayed. There are many ways to do it; you can use a simple box with a background color, a low-resolution image, some gradient, etc.
 43 |   In other words, this library focuses on loading the images once in view and supporting **loading patterns** around that.
 44 |   The presentational patterns are yours to decide!
 45 |   Fear not though, [we cover both patterns in the examples section](#examples).
 46 | 
 47 | ## Install
 48 | 
 49 | This package is distributed via [npm](https://www.npmjs.com/get-npm).
 50 | 
 51 | ```shell
 52 | $ npm install --save react-lazy-images
 53 | # or
 54 | $ yarn add react-lazy-images
 55 | ```
 56 | 
 57 | Then import according to your modules model and bundler, such as [Rollup](https://rollupjs.org/guide/en) and [Webpack](https://webpack.js.org/):
 58 | 
 59 | ```js
 60 | // ES Modules
 61 | // For all possible functions to import look at the documentation
 62 | import { LazyImage } from "react-lazy-images";
 63 | 
 64 | /// CommonJS modules
 65 | const { LazyImage } = require("react-lazy-images");
 66 | ```
 67 | 
 68 | A [UMD](https://github.com/umdjs/umd) version is also available on [unpkg](https://unpkg.com/):
 69 | 
 70 | ```html
 71 | <script src="https://unpkg.com/react-lazy-images/dist/react-lazy-images.umd.js"></script>
 72 | ```
 73 | 
 74 | ## Motivation
 75 | 
 76 | Browsers preload images; as soon as they encounter an `<img>` tag with a valid `src`, they kick off the request for the image (they even do this before the HTML has been parsed).
 77 | Even in cases where a certain image is not in the viewport, it will be requested.
 78 | This can have adverse effects for users, especially on mobile or metered connections.
 79 | 
 80 | This brings us to the basic premise of any Lazy Image Loading library:
 81 | 
 82 | - Have a way to observe the visibility of the DOM elements
 83 | - Prevent the browser from loading images directly
 84 | - Once an image is in view, instruct the browser to load it and place it in the element
 85 | 
 86 | In vanilla JS, this means "hiding" the actual `src` in a `data-src` attribute, and using classes to indicate state, e.g. `.isLazyLoaded .lazyLoad`.
 87 | On initialisation, a script queries for these classes and attributes, keeps track of visibily, and swaps `data-src` with an actual `src`, kicking off the browser request process.
 88 | It can elect to preload the Image, and only swap once loaded.
 89 | 
 90 | With React, all this implicit state management is brought into one place, since you do not have to stash loading information in the DOM and pick it back up again.
 91 | This can potentially mean a nicer, more composable codebase, and it was one of the main design goals for this library.
 92 | 
 93 | The way to do this visibility tracking has for the most part been listening for events such as scroll.
 94 | This is synchronous by nature and [can have performance implications](https://developers.google.com/web/fundamentals/performance/lazy-loading-guidance/images-and-video/#lazy_loading_images).
 95 | It also involves calling `getBoundingClientRect()` to calculate the interesection of the image with the viewport; this function causes relayout.
 96 | This was the motivation for browsers providing [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
 97 | Using this API is not specific to React; it just seems like a good fit for this task nowadays.
 98 | 
 99 | ## Usage
100 | 
101 | ### Quick Start
102 | 
103 | If you want to just dive in, do this:
104 | 
105 | ```jsx
106 | import { LazyImage } from "react-lazy-images";
107 | 
108 | <LazyImage
109 |   src="/img/porto_buildings_large.jpg"
110 |   alt="Buildings with tiled exteriors, lit by the sunset."
111 |   placeholder={({ imageProps, ref }) => (
112 |     <img ref={ref} src="/img/porto_buildings_lowres.jpg" alt={imageProps.alt} />
113 |   )}
114 |   actual={({ imageProps }) => <img {...imageProps} />}
115 | />;
116 | ```
117 | 
118 | :warning: It is important that you pass on the ref in placeholder, otherwise the detection of the element intersecting is impossible. :warning:
119 | 
120 | Note that while you can set the rendered components to be anything you want, you most likely want to use the same `src`, `srcSet` and `alt` attributes in an `<img>` eventually.
121 | To keep this consistent, and reduce repetition, the render callbacks pass those attributes back to you.
122 | 
123 | [You can play around with this library on Codesandbox](https://codesandbox.io/s/jnn9wjkj1w).
124 | 
125 | Additionally, make sure you understand [how to polyfill IntersectionObserver](#polyfill-intersectionobserver) and [strategies for when JS is not available](#fallback-without-javascript).
126 | 
127 | From then on:
128 | 
129 | - If you want to learn more about the API and the problem space, read the rest of this section.
130 | - If you need more fine-grained rendering, [read about `LazyImageFull`](#more-control-with-lazyimagefull).
131 | - If you want to list the props, see the [API reference](#api-reference).
132 | 
133 | ### Customising what is displayed
134 | 
135 | The render prop pattern is used throughout in `LazyImage`.
136 | The `LazyImage` component **handles the behaviour of tracking when the image is in view, but leaves the actual rendering up to the consumer**.
137 | Thus, whether you want to display a simple `<img>`, your own `<Image>`, or even wrapped elements, it is simple to do so:
138 | 
139 | ```jsx
140 | <LazyImage
141 |   src="/img/porto_buildings_large.jpg"
142 |   alt="Buildings with tiled exteriors, lit by the sunset."
143 |   // This is rendered first, notice how the src is different
144 |   placeholder={
145 |     ({imageProps, ref}) =>
146 |       <img ref={ref} src="/img/porto_buildings_lowres.jpg" alt={imageProps.alt} />
147 |   }
148 |   // This is rendered once in view; we use the src and alt above for consistency
149 |   actual={
150 |     ({imageProps}) =>
151 |       <img {...imageProps} />
152 |   }
153 | />
154 | 
155 | // Perhaps you want a container?
156 | <LazyImage
157 |   src="/img/porto_buildings_large.jpg"
158 |   alt="Buildings with tiled exteriors, lit by the sunset."
159 |   placeholder={
160 |     ({imageProps, ref}) =>
161 |       <div ref={ref} className={'LazyImage-Placeholder'}>
162 |         <img src="/img/porto_buildings_lowres.jpg" alt={imageProps.alt} />
163 |       </div>
164 |   }
165 |   actual={
166 |     ({imageProps}) =>
167 |       <div className={'LazyImage-Actual'}>
168 |         <img {...imageProps} />
169 |       </div>
170 |   }
171 | />
172 | ```
173 | 
174 | These props are there to instruct the component what to render in those places, and they take some useful information (in this case, a className) from the LazyImage.
175 | 
176 | ### More control with LazyImageFull
177 | 
178 | `LazyImage` should work for most cases, but you might need more fine-grained rendering.
179 | One use case would be doing animations with CSS transitions, where re-rendering the component (which `LazyImage` does) would not be sufficient.
180 | In those cases, consider `LazyImageFull`:
181 | 
182 | ```jsx
183 | import { LazyImageFull, ImageState } from "react-lazy-images";
184 | 
185 | // Function as child
186 | // `src`, `alt` and `srcSet` are passed back to the render callback for convenience/consistency
187 | <LazyImageFull src="/img/porto_buildings_large.jpg">
188 |   {({ imageProps, imageState, ref }) => (
189 |     <img
190 |       {...imageProps}
191 |       ref={ref}
192 |       src={
193 |         imageState === ImageState.LoadSuccess
194 |           ? imageProps.src
195 |           : "/img/porto_buildings_lowres.jpg"
196 |       }
197 |       style={{ opacity: ImageState.LoadSuccess ? "1" : "0.5" }}
198 |     />
199 |   )}
200 | </LazyImageFull>;
201 | ```
202 | 
203 | This component takes a function as a child, which accepts `{src, srcSet, imageState}`.
204 | The various image states are imported as `{ImageState}`, and you can conditionally render based on them.
205 | 
206 | This technique can give you more fine-grained rendering if needed, but can potentially be more verbose.
207 | Any of the presentational patterns presented that are possible with `LazyImage` are also possible with `LazyImageFull`.
208 | (The opposite is not necessarily true, or at least has more duplication).
209 | 
210 | In fact, if you check [`src/LazyImage.tsx`](./src/LazyImage.tsx), you will see that `LazyImage` is implemented in terms of `LazyImageFull`!
211 | 
212 | ### Load ahead and threshold
213 | 
214 | Further control over the Intersection Observer can be provided through the `observerProps` prop object:
215 | 
216 | ```jsx
217 | import { LazyImage } from "react-lazy-images";
218 | 
219 | <LazyImage
220 |   src="/img/porto_buildings_large.jpg"
221 |   alt="Buildings with tiled exteriors, lit by the sunset."
222 |   placeholder={/* the usual */}
223 |   actual={/* the usual */}
224 |   observerProps={{
225 |     rootMargin: "100px 0",
226 |     threshold: 0.3
227 |   }}
228 | />;
229 | ```
230 | 
231 | `rootMargin`: Margin around the window. This can have values similar to the CSS margin property, e.g. `"10px 20px 30px 40px"` (top, right, bottom, left) (defaulted to `"50px 0px"`)
232 | This can provide control if you want to request your image a certain number of pixels ahead of where the user is scrolling.
233 | 
234 | `threshold`: Number between 0 and 1 indicating the percentage that should be visible before a request is sent. (defaulted to `0.01`)
235 | 
236 | (See https://github.com/thebuilder/react-intersection-observer#api)
237 | 
238 | ### Load before swap
239 | 
240 | A common optimisation to the loading strategy is to preload the image before swapping it for the placeholder.
241 | In other words, once the image is in view, you can kick off a request to load the image, and only show it once fully loaded.
242 | This avoids presenting a half-loaded image (i.e. one that is still scanning top-to-bottom), and makes the transition smoother.
243 | 
244 | This behaviour is provided with the `src` prop:
245 | 
246 | ```jsx
247 | // Note that the actual src is also provided separately,
248 | // so that the image can be requested before rendering
249 | <LazyImage
250 |   src="/img/porto_buildings_large.jpg"
251 |   alt="Buildings with tiled exteriors, lit by the sunset."
252 |   placeholder={
253 |     ({imageProps, ref}) =>
254 |       <div ref={ref} className={`LazyImage-Placeholder`}">
255 |         <img src="/img/porto_buildings_lowres.jpg" alt={imageProps.alt} />
256 |       </div>
257 |   }
258 |   actual={
259 |     ({imageProps}) =>
260 |       <div className={`LazyImage-Actual`}>
261 |         <img {...imageProps} />
262 |       </div>
263 |   }
264 | />
265 | ```
266 | 
267 | There is another case if you are using `srcset` for your images; `LazyImage` needs that information to preload the correct image. You can provide it with the `srcSet` prop.
268 | 
269 | ### Loading and Error states
270 | 
271 | You can choose what to display on Loading and Error using the render props `loading` and `error`:
272 | 
273 | ```jsx
274 | <div className="bg-light-silver h5 w-100">
275 |   <LazyImage
276 |     src="/image/brokenimagenotherewhoops.jpg"
277 |     alt="Buildings with tiled exteriors, lit by the sunset."
278 |     actual={({ imageProps }) => <img {...imageProps} />}
279 |     placeholder={({ ref }) => <div ref={ref} />}
280 |     loading={() => (
281 |       <div>
282 |         <p className="pa3 f5 lh-copy near-white">Loading...</p>
283 |       </div>
284 |     )}
285 |     error={() => (
286 |       <div className="bg-light-red h-100 w-100">
287 |         <p>There was an error fetching this image :(</p>
288 |       </div>
289 |     )}
290 |   />
291 | </div>
292 | ```
293 | 
294 | ### Eager loading / Server-Side Rendering (SSR)
295 | 
296 | **What does SSR even mean in a lazy images context?**
297 | 
298 | If you recall the basic premise, then you will know that we "hide" the intended image and display a placeholder.
299 | For the actual image request to kick off, Javascript has to have loaded, and detected that the image is in the viewport.
300 | In cases where you are server-side rendering, there can be a non-neglible amount of time until Javascript is available (i.e. it has to download, parse, execute).
301 | For those cases, it would be beneficial if we can mark images to render with the intended/final src by default, so that the browser can start requesting them as soon as it gets the HTML.
302 | 
303 | This behaviour is available by using a `loadEagerly` prop:
304 | 
305 | ```jsx
306 | <LazyImage
307 |   loadEagerly
308 |   src="/img/porto_buildings_large.jpg"
309 |   alt="Buildings with tiled exteriors, lit by the sunset."
310 |   placeholder={({ imageProps, ref }) => (
311 |     <img ref={ref} src="/img/porto_buildings_lowres.jpg" alt={imageProps.alt} />
312 |   )}
313 |   actual={({ imageProps }) => <img {...imageProps} />}
314 | />
315 | ```
316 | 
317 | While the usage is simple, the patterns in your app will not necessarily be so.
318 | Think about the cases where it is beneficial to do this, and apply it with intent.
319 | Examples might be eager-loading hero images, preloading the first few elements in a list and so on.
320 | [Some of these use cases are provided as examples](#examples).
321 | 
322 | ### Debounce / Delay
323 | 
324 | In cases where you have a long list of images that the user might scroll through, then loading intermediate images can waste bandwidth and processing time.
325 | This is undesired.
326 | The way to handle it is with a **minimum duration** that the image has to stay within the viewport, before making the request.
327 | This is specified using the `debounceDurationMs` prop:
328 | 
329 | ```jsx
330 | <LazyImage
331 |   src="/img/porto_buildings_large.jpg"
332 |   alt="Buildings with tiled exteriors, lit by the sunset."
333 |   debounceDurationMs={1000}
334 |   placeholder={({ imageProps, ref }) => (
335 |     <img ref={ref} src="/img/porto_buildings_lowres.jpg" alt={imageProps.alt} />
336 |   )}
337 |   actual={({ imageProps }) => <img {...imageProps} />}
338 | />
339 | ```
340 | 
341 | ### Fallback without Javascript
342 | 
343 | If Javascript is disabled altogether by the user, then they will be stuck with the placeholder (and any images loaded eagerly).
344 | This is probably undesirable.
345 | 
346 | There are a few strategies for fallbacks.
347 | Most of them are variations on a `<noscript>` tag with the `actual` img and hiding the placeholder if JS is disabled.
348 | Here is what it looks like rendered:
349 | 
350 | ```jsx
351 | // In the <head>
352 | // Style applied only when JS is disabled
353 | // Hide the LazyImage (since the actual one will be displayed in its place)
354 | <noscript>
355 |   <style>
356 |     .LazyImage {
357 |       display: none;
358 |     }
359 |   </style>
360 | </noscript>
361 | 
362 | // Your component (as rendered)
363 | // Placeholder since JS has not run; will be hidden with the style above.
364 | <img class="LazyImage" src="/img/porto_buildings_lowres.jpg" alt="Buildings with tiled exteriors, lit by the sunset." />
365 | 
366 | // Declare the actual image as you would, inside a noscript
367 | <noscript>
368 |   <img src="/img/porto_buildings_large.jpg" alt="Buildings with tiled exteriors, lit by the sunset." />
369 | </noscript>
370 | ```
371 | 
372 | Until v0.3.0, this library had a fallback API, in the form of a `fallback` render prop.
373 | This has been disabled due to issues with `<noscript>` in React causing the fallback to always load.
374 | 
375 | (See https://github.com/facebook/react/issues/11423 for more details)
376 | 
377 | Current solutions involve either using `dangerouslySetInnerHTML`, which is not safe for arbitrary library use, or `ReactDOMServer.renderToStaticMarkup`.
378 | I thought it would be irresponsible to hide the fact that `dangerouslySetInnerHTML` is used from the user, so that excludes the first option.
379 | I also think that using the server method, albeit safe, would be messy with some bundling configurations (which would keep the entirety of `react-dom/server`).
380 | 
381 | **Silver lining:**
382 | 
383 | There is generally no case where `<noscript>` will be rendered by client-side react.
384 | This means that, if you are in charge of server-rendering and you trust your bundling setup, then you can have this fallback!
385 | Look at [`src/fallbackUtils.tsx`](./src/fallbackUtils.tsx) for a function that can work.
386 | You would probably do something like this:
387 | 
388 | ```jsx
389 | <LazyImage
390 |   src="actualImgSrc"
391 |   alt="alt description here"
392 |   placeholder={//the usual}
393 |   actual={//the usual}
394 | />
395 | <Fallback>
396 |   <img src="/img/porto_buildings_large.jpg" alt="Buildings with tiled exteriors, lit by the sunset." />
397 | </Fallback>
398 | ```
399 | 
400 | Don't forget to also hide the `.LazyImage` as shown above.
401 | 
402 | This may or may not be good enough.
403 | Please open an issue to discuss your needs if that is the case :)
404 | 
405 | ### Polyfill IntersectionObserver
406 | 
407 | IntersectionObserver is generally well-supported, but it is still important to polyfill it!
408 | [You can consult the usage data for IntersectionObserver here.](https://caniuse.com/#search=intersectionobserver)
409 | 
410 | The polyfill itself is pretty small, [on the order of 6k min, 2k gzipped](https://bundlephobia.com/result?p=intersection-observer@0.5.0).
411 | 
412 | [The polyfill is available through npm](http://npmjs.com/package/intersection-observer):
413 | 
414 | ```shell
415 | npm install --save intersection-observer
416 | ```
417 | 
418 | And import it at your app's entry point:
419 | 
420 | ```js
421 | import "intersection-observer";
422 | ```
423 | 
424 | [Polyfill.io is an alternative method of distributing the polyfill](https://polyfill.io) if you wish.
425 | 
426 | #### About the polyfill
427 | 
428 | _It is generally a good idea to know what you are adding to your codebase_
429 | 
430 | The polyfill behaviour is to [fall back to the older strategy](https://github.com/w3c/IntersectionObserver/tree/master/polyfill); "debounced scroll listener and calculate bounding rectangle", as mentioned above.
431 | It will not be as performant as the native IntersectionObserver, but likely no worse than most implementations of the older strategy.
432 | 
433 | ## Examples
434 | 
435 | ### About understanding the library and loading patterns
436 | 
437 | A variety of usage examples and recipes are provided in the form of Storybook.
438 | 
439 | [You can browse the documentation online](https://fpapado.github.io/react-lazy-images) or look at `stories/`.
440 | 
441 | Read the notes section either on Storybook or the story source if you are wondering about the specifics of each pattern demonstrated.
442 | 
443 | ### About abstracting over it and presentational patterns
444 | 
445 | [The starter on Codesandbox](https://codesandbox.io/s/jnn9wjkj1w) has a good basis for two popular presentational patterns.
446 | In particular, it shows intrinsic placeholders and fading in the actual image.
447 | 
448 | You might be thinking that this library has a lot of wiring exposed.
449 | This is very much intended.
450 | If this library were to provide presentational patterns out of the box, then it would lead to many issues and PRs about what ultimately is opinion.
451 | Being inclined to fork a library just to add a prop is not a nice situation to be in, compared to writing one abstracted component for your specific use case.
452 | The behaviour and loading patterns are configurable, because those are what this library is about.
453 | The presentation can be derived from those plus, crucially, any specific needs your application has.
454 | 
455 | ## API Reference
456 | 
457 | **`<LazyImage />`** accepts the following props:
458 | 
459 | | Name                   | Type                                                                      | Default                                   | Required | Description                                                                                                                                                                |
460 | | ---------------------- | ------------------------------------------------------------------------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
461 | | **src**                | String                                                                    |                                           | true     | The source of the image to load                                                                                                                                            |
462 | | **alt**                | String                                                                    |                                           | false    | The alt text description of the image you are loading                                                                                                                      |
463 | | **srcSet**             | String                                                                    |                                           | false    | If your images use srcset, you can pass the `srcSet` prop to provide that information for preloading.                                                                      |
464 | | **sizes**              | String                                                                    |                                           | false    | If your images use srcset, the sizes attribute helps the browser decide which source to load.                                                                              |
465 | | **actual**             | Function (render callback) of type ({imageProps}) => React.ReactNode      |                                           | true     | Component to display once image has loaded                                                                                                                                 |
466 | | **placeholder**        | Function (render callback) of type ({imageProps, ref}) => React.ReactNode | undefined                                 | true     | Component to display while no request for the actual image has been made                                                                                                   |
467 | | **loading**            | Function (render callback) of type () => React.ReactNode                  | placeholder                               | false    | Component to display while the image is loading                                                                                                                            |
468 | | **error**              | Function (render callback) of type () => React.ReactNode                  | actual (broken image)                     | false    | Component to display if the image loading has failed (render prop)                                                                                                         |
469 | | **debounceDurationMs** | Number                                                                    | N/A                                       | false    | The minimum duration that the image has to be in the viewport before starting to load, in ms. This can help avoid loading images while the user scrolls quickly past them. |
470 | | **loadEagerly**        | Boolean                                                                   | false                                     | false    | Whether to skip checking for viewport and always show the 'actual' component                                                                                               |
471 | | **observerProps**      | {threshold: number, rootMargin: string}                                   | {threshold: 0.01, rootMargin: "50px 0px"} | false    | Subset of props for the IntersectionObserver                                                                                                                               |
472 | | **experimentalDecode** | Boolean                                                                   | false                                     | false    | Decode the image off-main-thread using the Image Decode API. Test before using!                                                                                            |
473 | 
474 | **`<LazyImageFull />`** accepts the following props:
475 | 
476 | | Name                   | Type                                                                | Default                                   | Required | Description                                                                                           |
477 | | ---------------------- | ------------------------------------------------------------------- | ----------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
478 | | **src**                | String                                                              |                                           | true     | The source of the image to load                                                                       |
479 | | **alt**                | String                                                              |                                           | false    | The alt text description of the image you are loading                                                 |
480 | | **srcSet**             | String                                                              |                                           | false    | If your images use srcset, you can pass the `srcSet` prop to provide that information for preloading. |
481 | | **sizes**              | String                                                              |                                           | false    | If your images use srcset, the sizes attribute helps the browser decide which source to load.         |
482 | | **debounceDurationMs** | Number                                                              | N/A                                       | false    | The minimum duration that the image has to be in the viewport before starting to load, in ms.         |
483 | | **loadEagerly**        | Boolean                                                             | false                                     | false    | Whether to skip checking for viewport and always show the 'actual' component                          |
484 | | **observerProps**      | {threshold: number, rootMargin: string}                             | {threshold: 0.01, rootMargin: "50px 0px"} | false    | Subset of props for the IntersectionObserver                                                          |
485 | | **children**           | Function of type ({imageProps, imageState, ref}) => React.ReactNode |                                           | true     | Function to call that renders based on the props and state provided to it by LazyImageFull            |
486 | | **experimentalDecode** | Boolean                                                             | false                                     | false    | Decode the image off-main-thread using the Image Decode API. Test before using!                       |
487 | 
488 | [You can consult Typescript types in the code](./src/LazyImage.tsx) for more context.
489 | 
490 | ## Feedback
491 | 
492 | I have some specific questions that I would like input on. If you want to go exploring, or have used the library and had gripes with it, then see [`FEEDBACK.md`](./FEEDBACK.md) and let's have a discussion!
493 | 
494 | ## Roadmap
495 | 
496 | See [`ROADMAP.md`](./ROADMAP.md) for information and ideas about where the project is headed.
497 | 
498 | ## Contributing
499 | 
500 | I would love to have contributions on this! Are there more patterns that we can expose and simplify? Is something not clear? See `CONTRIBUTING.md` for details.
501 | 
502 | ## Thanks and Inspiration
503 | 
504 | Here are some resources whose ideas resonate with me and have informed this library.
505 | 
506 | - Jeremy Wagner's writing on [Lazy Loading Images and Video](https://developers.google.com/web/fundamentals/performance/lazy-loading-guidance/images-and-video/) is a good reference for the problem and solutions space.
507 | 
508 | - The library backing this one, [react-intersection-observer](https://github.com/thebuilder/react-intersection-observer).
509 |   Further thanks for demonstrating Storybook as documentation for lazy-loading.
510 | 
511 | - [José M. Pérez has a good resource on lazy loading](https://jmperezperez.com/high-performance-lazy-loading/)
512 | 
513 | - [Paul Lewis' implementation of lazy image loading](https://github.com/GoogleChromeLabs/sample-media-pwa/blob/master/src/client/scripts/helpers/lazy-load-images.js) has the concept of pre-loading images before swapping.
514 | 
515 | - [Dave Rupert has a good guide on intrinsic image placeholders](https://daverupert.com/2015/12/intrinsic-placeholders-with-picture/)
516 | 
517 | ## License
518 | 
519 | MIT License © Fotis Papadogeorgopoulos
520 | 


--------------------------------------------------------------------------------