https://github.com/morganney/background-image-size-hook
React hook to get the size in pixels of a CSS background image
https://github.com/morganney/background-image-size-hook
background-image hooks pixels react size
Last synced: 30 days ago
JSON representation
React hook to get the size in pixels of a CSS background image
- Host: GitHub
- URL: https://github.com/morganney/background-image-size-hook
- Owner: morganney
- Created: 2021-10-01T02:52:58.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2021-10-01T15:56:06.000Z (over 4 years ago)
- Last Synced: 2025-09-15T17:15:42.044Z (9 months ago)
- Topics: background-image, hooks, pixels, react, size
- Language: JavaScript
- Homepage:
- Size: 134 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# [`background-image-size-hook`](https://www.npmjs.com/package/background-image-size-hook)
[](https://codecov.io/gh/morganney/background-image-size-hook)
React hook to get the size of CSS background images.
## Usage
First `npm i background-image-size-hook react react-dom`.
Then when you want to change the dimensions of an element based on the size of its loaded background image:
```js
import { useBackgroundImageSize } from 'background-image-size-hook'
import styled from 'styled-components'
const Box = styled.div`
background-image: url('https://other-domain.com/images/cool.png');
width: ${({ image }) => image.width}px;
height: ${({ image }) => image.height}px;
`
const App = () => {
const [ref, image] = useBackgroundImageSize()
// Use a default while the background image is asynchronously re-loading
const defaultSize = { width: 200, height: 200 }
return
}
```
Alternatively, you can hide the element with CSS until the background-image size is known:
```js
const Box = styled.div`
background-image: url('https://other-domain.com/images/cool.png');
display: ${({ image }) => image ? 'block' : 'none'};
width: ${({ image }) => image?.width ?? 200}px;
height: ${({ image }) => image?.height ?? 200}px;
`
const App = () => {
const [ref, image] = useBackgroundImageSize()
return (
<>
{!image && }
>
)
}
```
## Advanced Usage
Beyond the simple use case of one static background image, more complex use cases require different hook behavior.
### Multiple Background Images
If the element has multiple background images then an array of objects will be returned instead of an object. Background images not referenced by a `url` will be ignored:
```js
const Box = styled.div`
background-image:
linear-gradient(rgba(0, 0, 255, 0.5), rgba(255, 255, 0, 0.5)),
url('https://other-domain.com/images/cool.png'),
url('data:image/png;base64,iRxVB0…');
`
const App = () => {
const [ref, images] = useBackgroundImageSize()
console.log(images) // Array of two objects for each background image (once loaded)
return
}
```
### Dynamic Background Images
If you use dynamic imports to load background images, for instance gravatars or tenant logos, and use a JavaScript bundler that supports loaders like [webpack](https://webpack.js.org/loaders/) or [esbuild](https://esbuild.github.io/api/#loader), then you can pass the resolved urls from the imports to the hook, so that the calculation of the background image size is dependent upon changes to the resolved url. This can also be achieved with the [mutliple dependencies](#multiple-dependencies) approach explained below by having the dynamic import state (`logo`) as a dependency.
```js
const Box = styled.div`
display: ${({ image }) => (image ? 'block' : 'none')};
background-image: url('${({ image }) => image?.src}');
width: ${({ image }) => image?.width ?? 200}px;
height: ${({ image }) => image?.height ?? 100}px;
`
const App = () => {
const { tenantId } = useContext(Context)
const [logo, setLogo] = useState('')
const [ref, image] = useBackgroundImageSize(logo)
useEffect(() => {
const fetchTenantLogo = async () => {
try {
const logoImport = await import(`./assets/${tenantId}/logo.png`)
setLogo(logoImport.default)
} catch {
setLogo('defaultLogo.svg')
}
}
fetchTenantLogo()
}, [tenantId])
return (
<>
{!image && }
>
)
}
```
If you want to pass urls from multiple dynamic background images, then use an array but make sure its reference does not change across renders, i.e. it is memoized:
```js
const urls = useMemo(() => [urlA, urlB], [urlA, urlB])
const [ref, images] = useBackgroundImageSize(urls)
```
### Multiple Dependencies
If you want to control when the background image size is computed based on other dependencies you can get a reference to the hook's callback by passing `true`. In this case the hook will return a callback function that can be called when one of the dependencies changes to get the background image size.
```js
const App = () => {
const [ref, images, getImageSizes] = useBackgroundImageSize(true)
useEffect(() => {
getImageSizes()
}, [getImageSizes, dep1, dep2, etc])
return
}
```
## About the Ref
To determine the exact width and height in pixels of the background image, it is reloaded into a dynamic image element (not attached to any DOM tree) which is an asynchronous process. Therefore, in all use cases you must attach the `ref` to the element with the background image to help prevent memory leaks, i.e. prevent the hook from potentially calling `setState` on an unmounted component. When no URLs are passed to the hook, the `ref` is used to get the URL of the background image, in addition to helping prevent a memory leaks.