pixboost-react

Library for integrating Pixboost API into the React applications.

Table of Contents:

• Installation
• Examples
• Responsive images
  • Which one to use?
  • HiDpiPicture
  • Picture
• Non-responsive images
• Configuration
• Browsers Support
• Build

Installation

To install the library:

npm install --save pixboost-react

There are 3 components that library provides:

• HiDpiPicture and Picture for responsive images.
• Image for images that don't need to change size depending on the device.

Library supports React version 14+.

Examples

You can find examples of how to use components in the example application.

Example application is also deployed at http://www.midday.coffee/react-demo/index.html

Responsive images

There are two types of responsive images components available in the library. Both implementations are using <picture> tag for high dpi screens optimisation.

• HiDpiPicture - Using combination of srcset and sizes attributes, so browser can pick the most suitable one.
• Picture - Displays fixed sizes images on defined media breakpoints

Which one to use?

HiDpiPicture is preferred for large images because any up-scaling artifacts will be more visible to the user on the screens with DPI > 1. Examples are hero banners, product images, zoom-in images.

Note that you would also need original images to be in a good quality and at least 3x of intended viewports size. For instance, if your product image takes up to 1000px then the original image should be at least 3000px wide.

Picture and Image are a good choice for small images like thumbnails, icons, etc.

HiDpiPicture

HiDpiPicture is a modern way of implementing responsive images using srcset and sizes attributes where we provide browser with variants of the image and visual size constraints to display. The browser then will make hard work for us and pick the best option to load and display.

Example:

    // Reusable configuration
    const pixboostConfig = {
        apiKey: 'MTg4MjMxMzM3MA__',
        domain: 'pixboost.com',
        breakpoints: {
            lg: {media: '(min-width: 990px)'},
            md: {media: '(min-width: 640px)'},
            sm: {}
        }
    };

    function YourComponent() {
      return (
              <HiDpiPicture alt="YO"
                            config={testConfig}
                            breakpoints={{ // operation for each breakpoint width {WIDTH} and {HEIGHT} values replaced with generated width and specified height if any
                              sm: {op: 'fit?size={WIDTH}x{HEIGHT}', height: 600}, // operation and optional fixed height
                              md: {op: 'resize?size={WIDTH}'},
                              lg: {op: 'resize?size={WIDTH}'}
                            }}
                            sizes={{ // image width for each breakpoint
                              sm: '100vw',
                              md: '640px',
                              lg: '1500px'
                            }}
                            minWidth={300}  // minimum visible size of the image
                            maxWidth={3000} // maximum visible size of the image
                            src="//here.com/logo.png"
              />
      )
    }

Properties (mandatory properties marked with *):

| Property | Type | Default | Description | |--------------------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | src* | String | | Source url or path with alias to the source image. | | breakpoints* | Object | | Object that sets an option for each visual breakpoint. You can use only breakpoints that you specified in the configuration property | | breakpoints.op* | String | | Operation to perform. By default is optimise. You can use {WIDTH} and {HEIGHT} placeholders. | | breakpoints.height | Number | | Setting the fixed height for the image on the given breakpoint | | sizes* | Object | | Object that specifies width of the image for the particular breakpoint. See More Info. | | minWidth* | Number | | | | maxWidth* | Number | | | | config* | Object | | Configuration | | alt* | String | | alt text for an image | | lazy | Boolean | false | If true, then will enable lazy loading for the image. | | imgProps | Object | | Pass through props to <img> tag. |

Picture

Picture component renders different sizes of the image for different visual breakpoints.

Below is a simple example:

    //This is a reusable configuration
    const pixboostConfig = {
        apiKey: 'MTg4MjMxMzM3MA__',
        domain: 'pixboost.com',
        breakpoints: {
            lg: {media: '(min-width: 990px)'},
            md: {media: '(min-width: 640px)'},
            sm: {}
        }
    };

    class YourComponent extends Component {
        render() {
            return (
                <Picture alt={"gadgets"} breakpoints={
                    {
                        lg: {
                            //Will optimise image by default
                            src: 'https://cdn.pixabay.com/photo/2015/01/21/14/14/apple-606761_960_720.jpg'
                        },
                        md: {
                            src: 'https://cdn.pixabay.com/photo/2015/02/02/15/28/bar-621033_960_720.jpg',
                            op: 'fit?size=300x300'
                        },
                        sm: {
                            //We can hide image for certain breakpoints
                            hide: true
                        }
                    }
                } config={pixboostConfig}/>
            )
        }
    }

Properties (mandatory properties marked with *):

| Property | Type | Default | Description | |------------------|---------|----------|--------------------------------------------------------------------------------------------------------------------------------------| | breakpoints* | Object | | Object that sets an option for each visual breakpoint. You can use only breakpoints that you specified in the configuration property | | breakpoints.src* | String | | URL of the original image | | breakpoints.op | String | optimise | Operation to perform. By default is optimise. | | breakpoints.hide | Boolean | false | If true then will hide image on the breakpoint. | | config* | Object | | Configuration | | alt | String | | alt text for an image | | lazy | Boolean | true | If true, then will enable lazy loading for the picture. | | imgProps | Object | | Pass through props to <img> tag. |

Non-responsive images

An Image component will be rendered the same on all screen sizes.

Example:

    //This is a reusable configuration
    const pixboostConfig = {
        apiKey: 'MTg4MjMxMzM3MA__',
        domain: 'pixboost.com'
    };

    class YourComponent extends Component {
        render() {
            return (
                <Image src={'https://cdn.pixabay.com/photo/2016/05/10/15/29/bear-1383980_960_720.jpg'}
                       alt={'lazy bear'}
                       config={pixboostConfig}
                       op={'resize?size=200'}
                />
            )
        }
    }

Properties (mandatory properties marked with *):

| Property | Type | Default | Description | |----------|---------|---------|-------------------------------------------------------| | src* | String | | URL of the original image | | config* | Object | | Configuration | | alt | String | | alt text for an image | | lazy | Boolean | true | If true, then will enable lazy loading for the image. |

Configuration

| Property | Type | Default | Description | |-------------------|--------|---------|------------------------------------------------------------------------| | apiKey* | String | | Pixboost API key | | domain* | String | | Custom domain name that you setup or pixboost.com | | breakpoints | Object | | Key-Value pair of breakpoints that you are using for responsive images | | breakpoints.media | String | | Media query for the breakpoint |

Browsers Support

The library supports all major browsers including Chrome, Chromium based (including IE), Firefox, Safari.

Build

To build from sources:

npm install
npm run build

Result will be generated into the lib/ folder.