92 | ```
93 |
94 | will resolve to:
95 |
96 | ```js
97 |
98 | ```
99 |
100 | If the image cannot be loaded, **`
111 | )
112 | ```
113 |
114 | If an image has previously been attempted unsuccessfully, `react-image` will not retry loading it again until the page is reloaded.
115 |
116 | ### Show a "spinner" or other element before the image is loaded:
117 |
118 | ```js
119 | const myComponent = () => (
120 |
124 | )
125 | ```
126 |
127 | If an image was previously loaded successfully (since the last time the page was loaded), the loader will not be shown and the image will be rendered immediately instead.
128 |
129 | ### Show a fallback element if none of the images could be loaded:
130 |
131 | ```js
132 | const myComponent = () => (
133 |
137 | )
138 | ```
139 |
140 | ### NOTE:
141 |
142 | The following options only apply to the `
151 | )
152 | ```
153 |
154 | ### Loading images with a CORS policy
155 |
156 | When loading images from another domain with a [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes), you may find you need to use the `crossorigin` attribute. For example:
157 |
158 | ```js
159 | const myComponent = () => (
160 |
161 | )
162 | ```
163 |
164 | ### Animations and other advanced uses
165 |
166 | A wrapper element `container` can be used to facilitate higher level operations which are beyond the scope of this project. `container` takes a single property, `children` which is whatever is passed in by **React Image** (i.e. the final ` {
174 | return {children}
175 | }}
176 | />
177 | ```
178 |
179 | By default, the loader and unloader components will also be wrapped by the `container` component. These can be set independently by passing a container via `loaderContainer` or `unloaderContainer`. To disable the loader or unloader from being wrapped, pass a noop to `loaderContainer` or `unloaderContainer` (like `unloaderContainer={img => img}`).
180 |
181 | ## Recipes
182 |
183 | ### Delay rendering until element is visible (lazy rendering)
184 |
185 | By definition, **React Image** will try loading images right away. This may be undesirable in some situations, such as when the page has many images. As with any react element, rendering can be delayed until the image is actually visible in the viewport using popular libraries such as [`react-visibility-sensor`](https://www.npmjs.com/package/react-visibility-sensor). Here is a quick sample (psudocode/untested!):
186 |
187 | ```js
188 | import {Img} from 'react-image'
189 | import VisibilitySensor from 'react-visibility-sensor'
190 |
191 | const myComponent = () =>
192 |
194 | Something went wrong. {this.state.error?.message}
32 | }
33 |
34 | return this.props.children
35 | }
36 | }
37 |
--------------------------------------------------------------------------------
/dev/app.tsx:
--------------------------------------------------------------------------------
1 | import React, {
2 | Suspense,
3 | useState,
4 | useEffect,
5 | useRef,
6 | useLayoutEffect,
7 | } from 'react'
8 | import {createRoot} from 'react-dom/client'
9 | import {Img, useImage} from '../src/index'
10 | import {ErrorBoundary} from './ErrorBoundry'
11 |
12 | navigator.serviceWorker.register('/sw.js', {scope: './'})
13 | new EventSource('/esbuild').addEventListener('change', () => location.reload())
14 |
15 | const randSeconds = (min, max) =>
16 | Math.floor(Math.random() * (max - min + 1) + min)
17 |
18 | function Timer({delay}) {
19 | const [startTime, setStartTime] = useState(Date.now())
20 | const [elapsedTime, setElapsedTime] = useState(0)
21 | const maxTimeReached = elapsedTime / 1000 > delay
22 | const remainingTime = delay - Math.trunc(elapsedTime / 1000)
23 |
24 | useEffect(() => {
25 | if (maxTimeReached) return
26 | const timer = setTimeout(() => setElapsedTime(Date.now() - startTime), 1000)
27 | return () => clearTimeout(timer)
28 | }, [elapsedTime])
29 |
30 | useEffect(() => {
31 | setStartTime(Date.now())
32 | setElapsedTime(0)
33 | }, [delay])
34 |
35 | return (
36 |
37 | Delayed: {delay} seconds
38 | {!maxTimeReached && <>, image should show in: {remainingTime}s}
39 |
40 |
41 |
42 | )
43 | }
44 |
45 | function GlobalTimer({until}) {
46 | const [startTime] = useState(Date.now())
47 | const [elapsedTime, setElapsedTime] = useState(0)
48 | const maxTimeReached = elapsedTime / 1000 - 2 > until
49 |
50 | useEffect(() => {
51 | if (maxTimeReached) return
52 | const timer = setTimeout(() => setElapsedTime(Date.now() - startTime), 1000)
53 | return () => clearTimeout(timer)
54 | }, [elapsedTime])
55 |
56 | return (
57 | 40 |
41 |
58 |
71 | 72 | )} 73 |
74 |
75 | )
76 | }
77 |
78 | const HooksLegacyExample = ({rand}) => {
79 | const {src, isLoading, error} = useImage({
80 | srcList: [
81 | 'https://www.example.com/non-existant-image.jpg',
82 | `/delay/${rand * 1000}/https://picsum.photos/200`, // will be loaded
83 | ],
84 | useSuspense: false,
85 | })
86 |
87 | return (
88 | React Image visual tests
59 |
60 | Test will load on page load. For a test to pass, one or more images
61 | should show in a green box or the text "✅ test passed" should show.
62 | Note that test are delayed by a random amount of time.
63 |
64 | {!maxTimeReached ? (
65 | Elapsed seconds: {Math.trunc(elapsedTime / 1000)}
66 | ) : ( 67 | <> 68 |Max time elapsed!
69 | All images should be loaded at this point 70 |71 | 72 | )} 73 |
74 |
89 | 
}
94 | {!isLoading && !error && !src && (
95 |
98 | )
99 | }
100 |
101 | const HooksSuspenseExample = ({rand}) => {
102 | const {src} = useImage({
103 | srcList: [
104 | 'https://www.example.com/foo.png',
105 | `/delay/${rand * 1000}/https://picsum.photos/200`, // will be loaded
106 | ],
107 | })
108 |
109 | return (
110 | Using hooks Legacy
90 |Loading...
}
92 | {error && Error! {error.msg}
}
93 | {src && Nothing to show - thats not good!
96 | )}
97 |
111 |
112 |
113 | )
114 | }
115 |
116 | const ReuseCache = ({renderId}) => {
117 | const src = `https://picsum.photos/200?rand=${renderId}`
118 | const [networkCalls, setNetworkCalls] = useState(0)
119 |
120 | useEffect(() => {
121 | setTimeout(() => {
122 | const entires = performance.getEntriesByName(src)
123 | setNetworkCalls(entires.length)
124 | }, 1000)
125 | })
126 |
127 | return (
128 |
129 |
142 |
148 |
149 |
150 | Loading... (Suspense fallback)
}>
151 | Suspense should reuse cache and only make one network call
130 |
131 | {networkCalls < 1 && ❓ test pending}
132 | {networkCalls === 1 && ✅ test passed}
133 | {networkCalls > 1 && (
134 |
135 | ❌ test failed. If DevTools is open, ensure "Disable Cache" in the
136 | network tab is disabled
137 |
138 | )}
139 |
140 | Network Calls detected: {networkCalls} (expecting just 1)
141 | 142 |
143 | To test this manually, check the Network Tab in DevTools to ensure the
144 | url
145 |
147 | {src} was only called once
146 | 148 |
149 |
202 | Change src
203 |
204 |
205 | {loadedSecondSource === null && ❓ test pending}
206 | {loadedSecondSource === true && ✅ test passed}
207 | {loadedSecondSource === false && ❌ test failed}
208 |
209 | Src list:
210 | {src.map((url, index) => {
211 | return (
212 |
213 | {index + 1}.
215 | )
216 | })}
217 | {url}
214 | 218 |
219 | This test will load an image and then switch sources after 1 second. It
220 | should then rerender with the new source. To manually confirm, ensure
221 | the loaded image's source is the second item in the Src list
222 |
223 | 224 |
this is the unloader
}
230 | />
231 |
232 | )
233 | }
234 |
235 | function App() {
236 | const imageOn404 =
237 | 'https://i9.ytimg.com/s_p/OLAK5uy_mwasty2cJpgWIpr61CqWRkHIT7LC62u7s/sddefault.jpg?sqp=CJz5ye8Fir7X7AMGCNKz4dEF&rs=AOn4CLC-JNn9jj-oFw94oM574w36xUL1iQ&v=5a3859d2'
238 | const tmdbImg =
239 | 'https://image.tmdb.org/t/p/w500/kqjL17yufvn9OVLyXYpvtyrFfask.jpg'
240 |
241 | // http://i.imgur.com/ozEaj1Z.jpg
242 | const rand1 = randSeconds(1, 8)
243 | const rand2 = randSeconds(2, 10)
244 | const rand3 = randSeconds(2, 10)
245 | const rand4 = randSeconds(2, 10)
246 | const rand5 = randSeconds(2, 10)
247 | const [renderId, setRenderId] = useState(Math.random())
248 | const [swRegistered, setSwRegistered] = useState(false)
249 |
250 | useLayoutEffect(() => {
251 | navigator.serviceWorker.ready.then(() => {
252 | setSwRegistered(true)
253 | })
254 | }, [])
255 |
256 | if (!swRegistered) return Waiting for server...
257 |
258 | return (
259 | <>
260 |
285 |
286 |
287 |
313 |
288 |
293 |
294 |
289 |
292 |
295 |
305 |
296 | 
Loading...
}
302 | unloader={Should show
297 |❎ test failed
}
303 | />
304 |
306 | 
✅ test passed
}
311 | />
312 | Should not show anything
307 |
314 | 
Loading...
}
319 | unloader={Should show unloader
315 |Loading...✅ test passed
}
320 | />
321 |
322 |
323 |
325 |
326 |
329 | Loading... (Suspense fallback)
}>
330 |