@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