@imageboss/react

React components for ImageBoss image optimization. Render responsive, optimized images with automatic srcset generation, art-direction support, and seamless integration with the ImageBoss CDN.

Installation

npm install @imageboss/react
# or
yarn add @imageboss/react

Quick Start

import { ImageBoss } from '@imageboss/react';

function App() {
  return (
    <ImageBoss
      source="mywebsite-images"
      src="/photos/hero.jpg"
      sizes="100vw"
      imagebossParams={{ format: 'auto' }}
      htmlAttributes={{ alt: 'Hero image' }}
    />
  );
}

Components

ImageBoss

The main component for rendering optimized images.

import { ImageBoss } from '@imageboss/react';

// Responsive image with automatic srcset
<ImageBoss
  source="mysite"
  src="/photo.jpg"
  sizes="(min-width: 768px) 50vw, 100vw"
  imagebossParams={{ format: 'auto' }}
/>

// Fixed-size image with DPR srcset
<ImageBoss
  source="mysite"
  src="/photo.jpg"
  width={500}
  height={300}
  imagebossParams={{ format: 'auto' }}
/>

Props

| Prop | Type | Description | |------|------|-------------| | src | string | Image path (e.g., /images/photo.jpg) | | source | string | ImageBoss source name | | operation | string | cover, width, height, cdn, or cover modes like cover:center | | width | number | Fixed width in pixels | | height | number | Fixed height in pixels | | sizes | string | Responsive sizes attribute | | imagebossParams | object | ImageBoss options (format, blur, grayscale, etc.) | | htmlAttributes | object | HTML attributes for the img element | | disableSrcSet | boolean | Disable srcset generation | | attributeConfig | object | Remap attributes for lazysizes |

Picture & Source

For art-direction with different images at different breakpoints.

import { Picture, Source, ImageBoss } from '@imageboss/react';

<Picture>
  <Source
    source="mysite"
    src="/photo.jpg"
    width={1200}
    htmlAttributes={{ media: '(min-width: 1024px)' }}
  />
  <Source
    source="mysite"
    src="/photo.jpg"
    width={800}
    htmlAttributes={{ media: '(min-width: 768px)' }}
  />
  <ImageBoss
    source="mysite"
    src="/photo.jpg"
    width={500}
    htmlAttributes={{ alt: 'Responsive image' }}
  />
</Picture>

Background

Render images as CSS background-image.

import { Background } from '@imageboss/react';

<Background
  source="mysite"
  src="/hero.jpg"
  imagebossParams={{ w: 1920, h: 600, format: 'auto' }}
  className="hero-section"
>
  <h1>Hero Title</h1>
</Background>

ImageBossProvider

Share configuration across components.

import { ImageBossProvider, ImageBoss } from '@imageboss/react';

<ImageBossProvider
  source="mysite"
  imagebossParams={{ format: 'auto' }}
>
  {/* All ImageBoss components use provider values */}
  <ImageBoss src="/photo1.jpg" width={500} />
  <ImageBoss src="/photo2.jpg" width={500} />
  
  {/* Override specific values */}
  <ImageBoss src="/photo3.jpg" width={500} imagebossParams={{ blur: 4 }} />
</ImageBossProvider>

buildURL

Generate ImageBoss URLs without rendering.

import { buildURL } from '@imageboss/react';

const url = buildURL('mysite', '/photo.jpg', {
  operation: 'cover',
  width: 500,
  height: 300,
  options: { format: 'auto', blur: 4 },
});
// => https://img.imageboss.me/mysite/cover/500x300/format:auto,blur:4/photo.jpg

ImageBoss URL Structure

https://img.imageboss.me/:source/:operation/:dimensions/:options/path/to/image.jpg

• Operations: cover, width, height, cdn
• Cover modes: cover:center, cover:smart, cover:face, cover:entropy, cover:attention, etc.
• Options: format:auto, blur:4, grayscale:true, dpr:2, etc.

Lazy Loading

Use native lazy loading or lazysizes:

// Native lazy loading
<ImageBoss
  source="mysite"
  src="/photo.jpg"
  sizes="100vw"
  htmlAttributes={{ loading: 'lazy' }}
/>

// With lazysizes
<ImageBoss
  source="mysite"
  src="/photo.jpg"
  sizes="100vw"
  className="lazyload"
  attributeConfig={{
    src: 'data-src',
    srcSet: 'data-srcset',
    sizes: 'data-sizes',
  }}
/>

Development

# Install dependencies
npm install

# Run tests
npm test

# Run playground
npm run playground

# Build
npm run build

Release

This project uses changesets for versioning.

# Add a changeset
npm run changeset

# Version packages (CI or manual)
npm run version-packages

# Publish to npm
npm run release

License

MIT