> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cevoid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Optimization

> Optimize Cevoid CDN image URLs for responsive storefronts and different display densities.

Use this page when you fetch Cevoid image URLs and want to render them efficiently in a storefront. If you are looking for gallery or card implementation behavior, use [Analytics Overview](./analytics) or the [API Reference](/api-reference) instead.

## When to use this

Use image optimization when:

* you fetch raw Cevoid image URLs from the API
* you render those images in a custom storefront UI
* you want smaller responsive images instead of the original full-size asset

Cevoid image URLs return the original image by default. Add the `class` query parameter when you want a pre-optimized size from the CDN.

## Quickstart

1. Fetch or receive the original Cevoid image URL.
2. Add `?class=<size>` to request an optimized width.
3. Use the optimized URL in your storefront markup.
4. Add `srcset` only when you need responsive behavior across breakpoints.

Example:

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<img
  src="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640"
  alt="User generated content"
/>
```

## Available Image Classes

The Cevoid CDN provides several pre-optimized image sizes:

| Class      | Width (pixels)  | Use Case                            |
| ---------- | --------------- | ----------------------------------- |
| `original` | Full resolution | High-quality displays, print        |
| `1080`     | 1080px          | Desktop hero images, large displays |
| `750`      | 750px           | Tablet landscape, desktop cards     |
| `640`      | 640px           | Tablet portrait, large mobile       |
| `480`      | 480px           | Mobile landscape                    |
| `400`      | 400px           | Mobile portrait, thumbnails         |
| `320`      | 320px           | Small mobile screens                |
| `240`      | 240px           | Thumbnail grids                     |
| `160`      | 160px           | Small thumbnails, avatars           |

## Example: transform an API image URL

When you fetch posts from the API, you'll receive image URLs like this:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "WAz8eIbvDR60rouK",
  "images": [
    {
      "url": "https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT",
      "width": 1920,
      "height": 1080
    }
  ]
}
```

Transform the URL by adding the `class` parameter:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const originalUrl = 'https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT'
const optimizedUrl = `${originalUrl}?class=640`

console.log(optimizedUrl)
```

Result:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640
```

## Performance guidance

### Choose the Right Size

<Tip>
  Select the image class that best matches your display requirements. Using unnecessarily large images wastes bandwidth and slows loading times.
</Tip>

### Responsive Images

Use different image classes for different screen sizes:

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<img
  src="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=320"
  sizes="(max-width: 320px) 320px, (max-width: 640px) 640px, 1080px"
  alt="User generated content"
/>
```

### Pick the nearest useful class

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
function getOptimizedImageUrl(originalUrl, targetWidth) {
  const imageClasses = [160, 240, 320, 400, 480, 640, 750, 1080]
  const bestClass = imageClasses.find((size) => size >= targetWidth) || 'original'

  return `${originalUrl}?class=${bestClass}`
}

const imageUrl = 'https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT'
const optimized = getOptimizedImageUrl(imageUrl, 400)
```

## Best Practices

### 1. Match Image Size to Container

Always choose an image class that matches or slightly exceeds your container's display size:

```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
.image-container {
  width: 300px;
}
```

### 2. Consider Display Density

For high-density displays (Retina, etc.), use an image class that's 2x your container size:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const containerWidth = 200;
const pixelRatio = window.devicePixelRatio || 1;
const targetWidth = containerWidth * pixelRatio;

const optimizedUrl = getOptimizedImageUrl(originalUrl, targetWidth);
```

### 3. Lazy Loading

Combine image optimization with lazy loading for maximum performance:

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<img
  data-src="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640"
  class="lazy-load"
  alt="User generated content"
/>
```

### 4. Fallback Strategy

Always have a fallback for when optimized images fail to load:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
function handleImageError(img) {
  const originalUrl = img.src.split('?')[0]
  img.src = originalUrl
}
```

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<img
  src="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640"
  onerror="handleImageError(this)"
  alt="User generated content"
/>
```

<Note>
  The Cevoid CDN automatically handles caching and global distribution of optimized images, ensuring fast loading times for users worldwide.
</Note>

### 5. Preloading Critical Images

For above-the-fold images, consider preloading:

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<link rel="preload" as="image" href="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=1080">
```

<Warning>
  Don't preload too many images as this can actually slow down initial page load. Only preload the most critical, above-the-fold images.
</Warning>

## Related

* [API Reference](/api-reference)
* [Analytics Overview](./analytics)