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
appropriateImagesReact.scopeAppropriateImage(imageConfig, options)

Returns an AppropriateImage component 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.

For example:

const appropriateImagesReact = require('@mapbox/appropriate-images-react');
const AppropriateImage = appropriateImagesReact.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 by [scopeAppropriateImage].
It can render your image in two ways:

  • As an <img>.
    Usually you'll do this.
  • As the background image of an absolutely positioned <div>.
    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 <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

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

const React = require('react');
const appropriateImagesReact = require('@mapbox/appropriate-images-react');
const imageConfig = require('./path/to/my/image-config.js');

const AppropriateImage = appropriateImagesReact(imageConfig);

class MyPage extends React.PureComponent {
  render() {
    return (
      <div>
        <p>An appropriate image will be loaded below:</p>
        <AppropriateImage name="bear" style={{ maxWidth: '100%' }}/>
      </div>
    );
  }
}

GitHub