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

# Image Optimization

> Improve your website performance with Stormkit's framework-agnostic image optimization. Resize, crop, and intelligently focus images using simple URL parameters.

## Overview

Stormkit includes a powerful, framework-agnostic image optimization feature that allows you to resize and crop images on-the-fly through simple URL parameters. This feature helps improve your website's performance by delivering appropriately sized images to your users.

The image optimization service automatically processes images when specific query parameters are detected in the image URL. Optimized images are cached for improved performance on subsequent requests.

## Usage

To optimize an image, simply add query parameters to your image URL:

```
https://your-domain.com/path/to/image.jpg?size=WIDTHxHEIGHT&smart=true|false
```

## Parameters

| Parameter | Description                                                                  | Format                         | Example                      |
| --------- | ---------------------------------------------------------------------------- | ------------------------------ | ---------------------------- |
| `size`    | Specifies the desired dimensions                                             | `WIDTHxHEIGHT` or just `WIDTH` | `size=400x300` or `size=400` |
| `smart`   | Enables smart cropping to maintain focus on the important parts of the image | `true` or `false`              | `smart=true`                 |

## Examples

<CardGroup cols={2}>
  <Card title="Basic Resize" icon="expand">
    Resize maintaining aspect ratio

    ```
    /images/photo.jpg?size=400
    ```

    Resizes to 400px width while maintaining aspect ratio.
  </Card>

  <Card title="Specific Dimensions" icon="crop">
    Force exact dimensions

    ```
    /images/photo.jpg?size=400x300
    ```

    Forces image to be exactly 400px × 300px.
  </Card>

  <Card title="Smart Cropping" icon="brain">
    Intelligent focus preservation

    ```
    /images/photo.jpg?size=400x300&smart=true
    ```

    Crops to 400x300px while focusing on important parts.
  </Card>

  <Card title="Responsive Images" icon="mobile">
    Different sizes for different devices

    ```html theme={null}
    <picture>
      <source media="(max-width: 600px)" />
      <img src="/photo.jpg?size=1200" />
    </picture>
    ```
  </Card>
</CardGroup>

## Use Cases

### Responsive Images

Use different size parameters based on the user's device to deliver appropriate images:

```html theme={null}
<picture>
  <source media="(max-width: 600px)" />
  <source media="(max-width: 1200px)" />
  <img src="/images/photo.jpg?size=2048" alt="Description" />
</picture>
```

### Thumbnails with Smart Cropping

When creating thumbnails or profile pictures, use smart cropping to ensure the subject remains in focus:

```html theme={null}
<img src="/images/profile.jpg?size=150x150&smart=true" alt="Profile picture" />
```

### Gallery Optimization

```html theme={null}
<!-- Thumbnail -->
<img src="/gallery/photo1.jpg?size=200x200&smart=true" alt="Thumbnail" />

<!-- Full size view -->
<img src="/gallery/photo1.jpg?size=1200" alt="Full size" />
```

## Security and Limitations

<Warning>
  **Important Limits:**

  * **Maximum Dimensions**: 2048px (width or height). Requests exceeding this return the original image.
  * **Variant Limit**: Maximum of 5 optimized variants per original image to prevent storage abuse.
  * **Caching**: Optimized images are cached for 24 hours.
</Warning>

### Why These Limits?

* **Maximum dimensions** prevent abuse and ensure reasonable resource usage
* **Variant limit** prevents storage exhaustion from unlimited optimization requests
* **Caching** improves performance for subsequent requests

<Info>
  Additional variant requests beyond the 5-variant limit will return the original image.
</Info>

## Best Practices

### 1. Use Appropriate Sizes

Don't request images larger than you need:

```html theme={null}
<!-- Good: Request only what you need -->
<img src="/image.jpg?size=400" alt="Image" style="max-width: 400px" />

<!-- Bad: Requesting unnecessarily large image -->
<img src="/image.jpg?size=2048" alt="Image" style="max-width: 400px" />
```

### 2. Leverage Smart Cropping

Use smart cropping for thumbnails and profile pictures:

```html theme={null}
<!-- Smart cropping keeps the subject in focus -->
<img src="/avatar.jpg?size=150x150&smart=true" alt="Avatar" />
```

### 3. Implement Responsive Images

Serve different sizes for different screen sizes:

```html theme={null}
<img
  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
  src="/image.jpg?size=800"
  alt="Responsive image"
/>
```

### 4. Plan Your Variants

With a 5-variant limit, choose your sizes wisely:

```
Original: 2400x1600
Variants:
1. Thumbnail: 200x200 (smart)
2. Mobile: 600
3. Tablet: 1024
4. Desktop: 1920
5. Square crop: 800x800 (smart)
```

## Supported Formats

The image optimization service supports the following formats:

* **JPEG** - Best for photographs
* **PNG** - Best for graphics with transparency
* **WebP** - Modern format with excellent compression
* **GIF** - Non-animated GIFs only
* **TIFF** - High-quality images

<Info>
  Animated GIFs are not supported. The first frame will be used.
</Info>

## Error Handling

If an image cannot be optimized due to any reason (invalid image format, processing error, etc.), the system will return the original image without optimization.

This ensures your site never breaks due to image optimization failures.

## Performance Tips

<CardGroup cols={2}>
  <Card title="Pre-warm Cache" icon="fire">
    Request common image sizes during deployment to pre-warm the cache.
  </Card>

  <Card title="CDN Integration" icon="server">
    Optimized images work seamlessly with CDNs for global distribution.
  </Card>

  <Card title="Lazy Loading" icon="hourglass">
    Combine with lazy loading for optimal page load performance.
  </Card>

  <Card title="Monitor Usage" icon="chart-bar">
    Track which variants are actually used and adjust accordingly.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Image not resizing">
    * Verify the size parameter format is correct
    * Check if the image format is supported
    * Ensure the URL is properly encoded
    * Verify the domain has optimization enabled
  </Accordion>

  <Accordion title="Getting original image instead of optimized">
    * Check if you've exceeded the 5-variant limit
    * Verify dimensions don't exceed 2048px
    * Check if the image format is supported
    * Review server logs for processing errors
  </Accordion>

  <Accordion title="Smart cropping not working as expected">
    * Ensure smart=true parameter is set
    * Verify both width and height are specified
    * Remember: smart cropping analyzes image content
    * Try different size ratios for better results
  </Accordion>
</AccordionGroup>

## Need Help?

If you encounter any issues with the image optimization feature, please contact Stormkit support or open an issue on our GitHub repository.