React Integration#

The @snapkit-studio/react package provides seamless integration of Snapkit's image optimization capabilities into your React applications.

Installation#

Install Snapkit for your React project:

npm install @snapkit-studio/react
# or
yarn add @snapkit-studio/react
# or
pnpm add @snapkit-studio/react

Quick Start#

Environment Configuration#

First, set up your environment variables:

VITE_SNAPKIT_ORGANIZATION_NAME=your-organization-name
VITE_SNAPKIT_DEFAULT_QUALITY=85
VITE_SNAPKIT_DEFAULT_OPTIMIZE_FORMAT=auto

Basic Usage#

The simplest way to use Snapkit in your React application:

import { Image } from '@snapkit-studio/react';
 
function MyComponent() {
  return (
    <Image
      src="/project/hero.jpg"
      alt="Hero Image"
      width={800}
      height={600}
      priority
      transforms={{ format: 'auto' }}
    />
  );
}

With SnapkitProvider (Recommended)#

For applications with multiple images and centralized configuration:

import { SnapkitProvider, Image } from '@snapkit-studio/react';
 
function App() {
  return (
    <SnapkitProvider
      baseUrl="https://snapkit-cdn.snapkit.studio"
      organizationName="your-org"
      defaultQuality={85}
      defaultFormat="auto"
    >
      <YourApplication />
    </SnapkitProvider>
  );
}
 
function YourApplication() {
  return (
    <Image
      src="/hero.jpg"
      alt="Hero image"
      width={800}
      height={600}
    />
  );
}

Key Features#

Automatic Format Detection#

Snapkit automatically detects and serves the best format (AVIF, WebP, JPEG) based on browser support:

<Image
  src="/product.jpg"
  alt="Product"
  width={400}
  height={300}
  transforms={{ format: 'auto' }}
/>

Network-Aware Quality Adjustment#

Dynamic quality adjustment based on network conditions:

<Image
  src="/high-res.jpg"
  alt="High resolution image"
  width={1200}
  height={800}
  transforms={{ quality: 'auto' }}
/>

Visual Transformations#

Apply various visual effects and transformations:

// Grayscale effect
<Image
  src="/photo.jpg"
  transforms={{ grayscale: true }}
/>
 
// Blur effect
<Image
  src="/background.jpg"
  transforms={{ blur: 20 }}
/>
 
// Flip and rotate
<Image
  src="/icon.png"
  transforms={{
    flip: true,
    rotate: 90
  }}
/>

Region Extraction#

Extract specific regions from images:

<Image
  src="/large-image.jpg"
  transforms={{
    extract: {
      x: 100,
      y: 100,
      width: 400,
      height: 300
    }
  }}
/>

Performance Optimization#

Priority Loading#

For above-the-fold images that should load immediately:

<Image
  src="/hero-banner.jpg"
  priority={true}
  width={1200}
  height={600}
/>

Lazy Loading#

For below-the-fold images to improve initial page load:

<Image
  src="/footer-image.jpg"
  loading="lazy"
  width={600}
  height={400}
/>

Responsive Images#

Fill Mode#

For images that should fill their container:

<div className="relative w-full h-64 rounded-lg overflow-hidden">
  <Image
    src="/background.jpg"
    fill={true}
    className="object-cover"
    alt="Background"
  />
</div>

Responsive Sizing#

With srcset generation for different screen sizes:

<Image
  src="/responsive.jpg"
  width={800}
  height={600}
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
  transforms={{ format: 'auto' }}
/>

Bundle Size Optimization#

Optimized Import (~9KB)#

For applications where bundle size is critical:

import { Image } from '@snapkit-studio/react/image';
 
// Use without provider - configure via props
<Image
  src="/photo.jpg"
  baseUrl="https://your-cdn.snapkit.studio"
  organizationName="your-org"
  width={400}
  height={300}
/>

Full Bundle (~22KB)#

When using provider pattern for centralized configuration:

import { Image, SnapkitProvider } from '@snapkit-studio/react';

Advanced Configuration#

Custom Loader#

Create a custom image loader for specific requirements:

const customLoader = ({ src, width, quality }) => {
  const params = new URLSearchParams({
    w: width.toString(),
    q: (quality || 75).toString(),
  });
 
  return `https://your-cdn.snapkit.studio/${src}?${params}`;
};
 
<Image
  loader={customLoader}
  src="image.jpg"
  width={400}
  height={300}
/>

TypeScript Support#

Full TypeScript support with type-safe transforms:

import { Image, type ImageTransforms } from '@snapkit-studio/react';
 
const transforms: ImageTransforms = {
  format: 'webp',
  quality: 90,
  blur: 0,
  grayscale: false,
};
 
<Image
  src="/typed-image.jpg"
  transforms={transforms}
  width={600}
  height={400}
/>

Best Practices#

Use Provider for Multiple Images: When your application has many images, use SnapkitProvider to avoid repetitive configuration.
Optimize Critical Images: Use priority={true} for above-the-fold images to improve LCP (Largest Contentful Paint).
Lazy Load Below-Fold Images: Use loading="lazy" for images not immediately visible to improve initial page load.
Set Appropriate Dimensions: Always provide width and height to prevent layout shift (CLS).
Use Auto Format: Let Snapkit automatically select the best format with transforms={{ format: 'auto' }}.

Migration Guide#

From Native IMG Tags#

// Before
<img
  src="/image.jpg"
  alt="Description"
  width="400"
  height="300"
/>
 
// After
<Image
  src="/image.jpg"
  alt="Description"
  width={400}
  height={300}
  transforms={{ format: 'auto' }}
/>

From Other Image Components#

Most image components can be replaced directly with minimal changes:

// Before (other library)
<OptimizedImage
  source="/photo.jpg"
  width={500}
  height={400}
/>
 
// After (Snapkit)
<Image
  src="/photo.jpg"
  width={500}
  height={400}
  transforms={{ format: 'auto' }}
/>

Troubleshooting#

Common Issues#

Images not loading: Ensure your baseUrl and organizationName are correctly configured.
TypeScript errors: Make sure you have the latest version of @snapkit-studio/react installed.
Layout shift: Always provide explicit width and height attributes.
Blurry images: Check that you're not scaling images beyond their original dimensions.

Browser Support#

AVIF: Chrome 85+, Firefox 93+, Safari 16+
WebP: Chrome 23+, Firefox 65+, Safari 14+
Lazy Loading: Chrome 76+, Firefox 75+, Safari 15.4+

Key Features Summary#

Automatic format detection (AVIF, WebP, JPEG)
Next.js Image component compatible
TypeScript support
Responsive image loading
DPR-based optimization
Lazy loading
Network-aware quality adjustment