@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;
- 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).
API
scopeAppropriateImage
scopeAppropriateImage(imageConfig, [options])
A named import for ES2015 modules, or a property on the CommonJS module.
import { scopeAppropriateImage } from '@mapbox/appropriate-images-react';
// OR
const scopeAppropriateImage = require('@mapbox/appropriate-images-react').scopeAppropriateImage;
Returns an AppropriateImage component scoped according to your appropriate-images configuration and options.
imageConfig
TypeObject
.
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.For example:
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.
AppropriateImage
This is the component that is returned byscopeAppropriateImage
.
It can render your image in two ways:- As an
<img>
.
- As the background image of an absolutely positioned
<div>
.
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
Typestring
.
Required.The id of the image to render. Must correspond with a key in the appropriate-images configuration.
background
Typeboolean
.
Default: false
.By default, an
<img>
element is rendered.
If this option is true
, you instead get a <div>
, absolutely positioned to fill its container, whose background-image
will be the appropriate image.backgroundPosition
Typestring
.
Default: 'center center'
.Only meaningful if
background={true}
.
Any background-position
value will do.backgroundSize
Typestring
.
Default: 'cover'
.Only meaningful if
background={true}
.
Any background-size
value will do.Example
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 (
<div>
<p>An appropriate image will be loaded below:</p>
<AppropriateImage imageId="bear" style={{ maxWidth: '100%' }}/>
</div>
);
}
}