Examples showing how to use the resized, optimized images that you generated with appropriate-images in React

Downloads in past


1322.2.02 years ago5 years agoMinified + gzip package size for @mapbox/appropriate-images-react in KB


Build Status
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.

(If you aren't using React but want to use your appropriate-images in the browser, check out appropriate-images-get-url).



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.


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.


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}`)
Type: number. Default: 1.3.
See the same option for appropriate-images-get-url.


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.


All props you pass other than those documented below are applied directly to the rendered element (e.g. alt, id, data-*, aria-*).
Type string. Required.
The id of the image to render. Must correspond with a key in the appropriate-images configuration.
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.
Type string. Default: 'center center'.
Only meaningful if background={true}. Any background-position value will do.
Type string. Default: 'cover'.
Only meaningful if background={true}. Any background-size value will do.


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 (
        <p>An appropriate image will be loaded below:</p>
        <AppropriateImage imageId="bear" style={{ maxWidth: '100%' }}/>