npm package: @imageboss/react
Description: React components for ImageBoss image optimization
Author: ImageBoss
Latest version: 1.0.0

# @imageboss/react

React components for [ImageBoss](https://imageboss.me) image optimization. Render responsive, optimized images with automatic srcset generation, art-direction support, and seamless integration with the ImageBoss CDN.

## Installation

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

## Quick Start

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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:

```tsx
// 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

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run playground
npm run playground

# Build
npm run build
```

## Release

This project uses [changesets](https://github.com/changesets/changesets) for versioning.

```bash
# Add a changeset
npm run changeset

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

# Publish to npm
npm run release
```

## License

MIT