Given an appropriate-images configuration render the appropriate size variant of an image

Given an appropriate-images configuration render the appropriate size variant of an image

After you've generated resized, optimized images with appropriate-images, you'll want to use them in the browser.

@mapbox/appropriate-images-react

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).

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

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:

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 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 { 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>
    );
  }
}

Github Repository

Tags: #React #Images