Gathering detailed insights and metrics for react-image
React.js <img> tag rendering with multiple fallback & loader support
Installations
npm install react-imageDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS, UMD
Node Version
18.14.2
NPM Version
9.5.0
Score
92.9
Supply Chain
94.4
Quality
76.2
Maintenance
100
Vulnerability
100
License
Releases
Unable to fetch releases
Contributors
23
Unable to fetch Contributors
Languages
3
TypeScript
JavaScript
HTML
TypeScript (67.37%)
JavaScript (32.17%)
HTML (0.46%)
Love this project? Help keep it running — sponsor us today! 🚀
Developer
mbrevda
Download Statistics
Total Downloads
18,892,981
Last Day
18,625
Last Week
98,455
Last Month
404,667
Last Year
4,213,609
GitHub Statistics
MIT License
1,208 Stars
1,932 Commits
91 Forks
6 Watchers
10 Branches
23 Contributors
Updated on Feb 11, 2025
Bundle Size
3.49 kB
Minified
1.25 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
4.1.0
Package Id
react-image@4.1.0
Unpacked Size
39.34 kB
Size
11.07 kB
File Count
20
NPM Version
9.5.0
Node Version
18.14.2
Published on
Mar 10, 2023
Total Downloads
Cumulative downloads
Total Downloads
18,892,981
Last Day
6%
18,625
Compared to previous day
Last Week
14.9%
98,455
Compared to previous week
Last Month
23.5%
404,667
Compared to previous month
Last Year
-2.7%
4,213,609
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Peer Dependencies
3
Dev Dependencies
38
@babel/cli@babel/core@babel/plugin-proposal-class-properties@babel/plugin-proposal-object-rest-spread@babel/plugin-transform-runtime@babel/preset-env@babel/preset-react@babel/preset-typescript@babel/runtime@testing-library/react@types/jest@types/react@types/react-dombabel-corebabel-jestbabel-loaderbabel-plugin-transform-inline-environment-variablescodecovcommanderexpresshtml-webpack-pluginjestjest-environment-jsdomprettierreactreact-domrolluprollup-plugin-babelrollup-plugin-babel-minifyrollup-plugin-node-resolvesemverserve-staticts-jestts-loadertypescriptwebpackwebpack-cliwebpack-dev-server
React Image 🏝 🏖 🏜
React Image is an <img> tag replacement and hook for React.js, supporting fallback to alternate sources when loading an image fails.
React Image allows one or more images to be used as fallback images in the event that the browser couldn't load the previous image. When using the component, you can specify any React element to be used before an image is loaded (i.e. a spinner) or in the event that the specified image(s) could not be loaded. When using the hook this can be achieved by wrapping the component with <Suspense> and specifying the fallback prop.
React Image uses the useImage hook internally which encapsulates all the image loading logic. This hook works with React Suspense by default and will suspend painting until the image is downloaded and decoded by the browser.
Getting started
- To include the code locally in ES6, CommonJS, or UMD format, install
react-imageusing npm:
npm install react-image --save
- To include the code globally from a cdn:
1<script src="https://unpkg.com/react-image/umd/index.js"></script>
Dependencies
react-image has no external dependencies, aside from a version of react and react-dom which support hooks and @babel/runtime.
Documentation
You can use the standalone component, documented below, or the useImage hook.
useImage():
The useImage hook allows for incorporating react-image's logic in any component. When using the hook, the component can be wrapped in <Suspense> to keep it from rendering until the image is ready. Specify the fallback prop to show a spinner or any other component to the user while the browser is loading. The hook will throw an error if it fails to find any images. You can wrap your component with an Error Boundary to catch this scenario and do/show something.
Example usage:
1import React, {Suspense} from 'react' 2import {useImage} from 'react-image' 3 4function MyImageComponent() { 5 const {src} = useImage({ 6 srcList: 'https://www.example.com/foo.jpg', 7 }) 8 9 return <img src={src} /> 10} 11 12export default function MyComponent() { 13 return ( 14 <Suspense> 15 <MyImageComponent /> 16 </Suspense> 17 ) 18}
useImage API:
-
srcList: a string or array of strings.useImagewill try loading these one at a time and returns after the first one is successfully loaded -
imgPromise: a promise that accepts a url and returns a promise which resolves if the image is successfully loaded or rejects if the image doesn't load. You can inject an alternative implementation for advanced custom behaviour such as logging errors or dealing with servers that return an image with a 404 header -
useSuspense: boolean. By default,useImagewill tell React to suspend rendering until an image is downloaded. Suspense can be disabled by setting this to false.
returns:
src: the resolved image addressisLoading: the currently loading status. Note: this is never true when using Suspenseerror: any errors ecountered, if any
Standalone component (legacy)
When possible, you should use the useImage hook. This provides for greater flexibility and provides support for React Suspense.
Include react-image in your component:
1import {Img} from 'react-image'
and set a source for the image:
1const myComponent = () => <Img src="https://www.example.com/foo.jpg" />
will resolve to:
1<img src="https://www.example.com/foo.jpg">
If the image cannot be loaded, <img> will not be rendered, preventing a "broken" image from showing.
Multiple fallback images:
When src is specified as an array, react-image will attempt to load all the images specified in the array, starting at the first and continuing until an image has been successfully loaded.
1const myComponent = () => ( 2 <Img 3 src={['https://www.example.com/foo.jpg', 'https://www.example.com/bar.jpg']} 4 /> 5)
If an image has previously been attempted unsuccessfully, react-image will not retry loading it again until the page is reloaded.
Show a "spinner" or other element before the image is loaded:
1const myComponent = () => ( 2 <Img 3 src={['https://www.example.com/foo.jpg', 'https://www.example.com/bar.jpg']} 4 loader={/*any valid react element */} 5 /> 6)
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.
Show a fallback element if none of the images could be loaded:
1const myComponent = () => ( 2 <Img 3 src={['https://www.example.com/foo.jpg', 'https://www.example.com/bar.jpg']} 4 unloader={/*any valid react element */} 5 /> 6)
NOTE:
The following options only apply to the <Img> component, not to the useImage hook. When using the hook you can inject a custom image resolver with custom behaviour as required.
Decode before paint
By default and when supported by the browser, react-image uses Image.decode() to decode the image and only render it when it's fully ready to be painted. While this doesn't matter much for vector images (such as svg's) which are rendered immediately, decoding the image before painting prevents the browser from hanging or flashing while the image is decoded. If this behaviour is undesirable, it can be disabled by setting the decode prop to false:
1const myComponent = () => ( 2 <Img src={'https://www.example.com/foo.jpg'} decode={false} /> 3)
Loading images with a CORS policy
When loading images from another domain with a CORS policy, you may find you need to use the crossorigin attribute. For example:
1const myComponent = () => ( 2 <Img src={'https://www.example.com/foo.jpg'} crossorigin="anonymous" /> 3)
Animations and other advanced uses
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 <img> or the loaders).
For example, to animate the display of the image (and animate out the loader) a wrapper can be set:
1<Img 2 src={'https://www.example.com/foo.jpg'} 3 container={(children) => { 4 return <div className="foo">{children}</div> 5 }} 6/>
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}).
Recipes
Delay rendering until element is visible (lazy rendering)
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. Here is a quick sample (psudocode/untested!):
1import {Img} from 'react-image' 2import VisibilitySensor from 'react-visibility-sensor' 3 4const myComponent = () => 5 <VisibilitySensor> 6 <Img src='https://www.example.com/foo.jpg'> 7 </VisibilitySensor>
Note: it is not necessary to use React Image to prevent loading of images past "the fold" (i.e. not currently visible in the window). Instead just use the native HTML <img> element and the loading="lazy" prop. See more here.
Animate image loading
see above
License
react-image is available under the MIT License
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
17 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10
Reason
no dangerous workflow patterns detected
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
8 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
- Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
- Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q
Reason
no SAST tool detected
Details
- Warn: no pull requests merged into dev branch
Reason
Found 0/30 approved changesets -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/buildDeploy.yml:1
- Info: no jobLevel write permissions found
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:32: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:51: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:61: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:62: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:65: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:71: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:86: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:110: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:111: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:114: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/buildDeploy.yml:122: update your workflow using https://app.stepsecurity.io/secureworkflow/mbrevda/react-image/buildDeploy.yml/master?enable=pin
- Info: 0 out of 12 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 5 third-party GitHubAction dependencies pinned
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'master'
Score
3.6
/10
Last Scanned on 2025-02-03
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More