https://github.com/mapbox/appropriate-images-react
Given an appropriate-images configuration, render the appropriate size variant of an image
https://github.com/mapbox/appropriate-images-react
docs-infrastructure
Last synced: 4 days ago
JSON representation
Given an appropriate-images configuration, render the appropriate size variant of an image
- Host: GitHub
- URL: https://github.com/mapbox/appropriate-images-react
- Owner: mapbox
- License: mit
- Archived: true
- Created: 2017-06-24T22:38:00.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2024-04-12T18:03:47.000Z (about 2 years ago)
- Last Synced: 2025-04-21T08:56:49.485Z (about 1 year ago)
- Topics: docs-infrastructure
- Language: JavaScript
- Size: 2.83 MB
- Stars: 13
- Watchers: 104
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-github-projects - appropriate-images-react - Given an appropriate-images configuration, render the appropriate size variant of an image ⭐13 `JavaScript` (📦 Legacy & Inactive Projects)
README
# @mapbox/appropriate-images-react
## Note: As of April 2024 this repository is no longer used or maintained.
[](https://travis-ci.com/mapbox/appropriate-images-react)
**Use in combination with [appropriate-images].**
After you've generated resized, optimized images with [appropriate-images], you'll want to use them in the browser.
If you like React, you'll want to use them with React.
You'll need to determine *which variant* of the image to load — that is, which size, and whether to load the `.webp` version or not.
This module does that.
Here are the steps it takes.
- Measures the element's available width with [react-simple-surveyor](https://github.com/mapbox/react-simple-surveyor);
- Combines that width with your [appropriate-images configuration] to get a URL, using [appropriate-images-get-url];
- Then renders the appropriate variant of the image.
(If you aren't using React but want to use your [appropriate-images] in the browser, check out [appropriate-images-get-url](https://github.com/mapbox/appropriate-images-get-url)).
## API
### scopeAppropriateImage
`scopeAppropriateImage(imageConfig, [options])`
A named import for ES2015 modules, or a property on the CommonJS module.
```js
import { scopeAppropriateImage } from '@mapbox/appropriate-images-react';
// OR
const scopeAppropriateImage = require('@mapbox/appropriate-images-react').scopeAppropriateImage;
```
Returns an [AppropriateImage component](#appropriateimage) scoped according to your [appropriate-images configuration] and options.
#### imageConfig
Type `Object`.
**Required**.
Your [appropriate-images configuration].
**Use the same configuration at run time, in the browser, as you do at build time, when generating the resized, optimized images.**
#### options
##### transformUrl
Type: `(originalUrl: string) => string`.
Default: `x => x`.
If you want to transform the URL in some way, use this function.
One use-case is to take advantage of Webpack's augmented `require()` to get the URL *that Webpack creates* — if, for example, you're adding a hash to the end of files loaded with [Webpack's file-loader](https://github.com/webpack-contrib/file-loader).
For example:
```js
import { scopeAppropriateImage } from '@mapbox/appropriate-images-react';
const AppropriateImage = scopeAppropriateImage(myImageConfig, {
transformUrl: url => require(`/my/image/directory/${url}`)
});
```
##### hiResRatio
Type: `number`.
Default: `1.3`.
See [the same option for appropriate-images-get-url](https://github.com/mapbox/appropriate-images-get-url#hiresratio).
### AppropriateImage
This is the component that is returned by [`scopeAppropriateImage`].
It can render your image in two ways:
- As an `![]()
`.
Usually you'll do this.
- As the background image of an absolutely positioned `
`.
This can be handy in situations when you want to take advantage of powerful CSS background properties like `background-size` and `background-position`.
#### props
All props you pass other than those documented below are applied directly to the rendered element (e.g. `alt`, `id`, `data-*`, `aria-*`).
##### imageId
Type `string`.
**Required**.
The id of the image to render.
Must correspond with a key in the [appropriate-images configuration].
##### background
Type `boolean`.
Default: `false`.
By default, an `![]()
` element is rendered.
If this option is `true`, you instead get a `
`, absolutely positioned to fill its container, whose `background-image` will be the appropriate image.
##### backgroundPosition
Type `string`.
Default: `'center center'`.
**Only meaningful if `background={true}`.**
Any `background-position` value will do.
##### backgroundSize
Type `string`.
Default: `'cover'`.
**Only meaningful if `background={true}`.**
Any `background-size` value will do.
## Example
```js
const React = require('react');
const { scopeAppropriateImage } = require('@mapbox/appropriate-images-react');
const imageConfig = require('./path/to/my/image-config.js');
const AppropriateImage = scopeAppropriateImage(imageConfig);
class MyPage extends React.PureComponent {
render() {
return (
An appropriate image will be loaded below:
);
}
}
```
[appropriate-images]: https://github.com/mapbox/appropriate-images
[appropriate-images configuration]: https://github.com/mapbox/appropriate-images#image-configuration
[appropriate-images-get-url]: https://github.com/mapbox/appropriate-images-get-url
[`scopeAppropriateImage`]: #scopeappropriateimage