Getting Started

Minimal Setup

Installation:
```
composer require spatie/statamic-responsive-images
```
No additional configuration is required for basic usage.

Fieldtype Usage: Define a responsive image field in your YAML:

-
  handle: hero_image
  field:
    type: responsive
    container: assets
    display: Hero Image

First Render: Use the responsive tag in Twig:
```
{{ responsive:hero_image }}
```
This generates a responsive <img> tag with srcset and sizes attributes.

Key First Use Case

Replace static image fields with the responsive fieldtype for art-directed images. For example, a hero section with different aspect ratios for mobile/desktop:

{{ responsive:hero_image ratio="16/9" md:ratio="3/1" }}

Implementation Patterns

Core Workflow

Fieldtype Configuration:
- Use use_breakpoints: true for art direction.
- Define breakpoints (e.g., sm, md, lg) in the field config or responsive-images.php.
- Example:
```
breakpoints:
  - sm
  - md
  - lg
```

Twig Integration:

Basic Usage:
```
{{ responsive:field_handle }}
```

Art Direction:

{{ responsive:field_handle ratio="1/1" md:ratio="16/9" lg:src="desktop_image" }}

Glide Parameters:

{{ responsive:field_handle glide:width="800" glide:blur="10" }}

GraphQL: Query responsive images in GraphQL:

{
  entries {
    data {
      id
      hero_image {
        responsive(ratio: "16/9") {
          sources {
            srcSet
            mediaString
          }
        }
      }
    }
  }
}

Integration Tips

Asset Containers: Exclude containers from responsive generation in responsive-images.php:
```
'excluded_containers' => ['temp-assets'],
```
Queue Jobs: For large sites, leverage queues (default: default). Configure in responsive-images.php:
```
'queue' => 'images',
```
Live Preview: Enable hot reload for Statamic’s live preview with:
```
php artisan responsive:regenerate
```
(Only needed if statamic.assets.image_manipulation.cache is true.)

Custom HTML: Publish views to override the default <img> tag:

php artisan vendor:publish --provider="Spatie\ResponsiveImages\ServiceProvider"

Performance Optimization

Lazy Generation: Set statamic.assets.image_manipulation.cache to false to generate images on-demand.

Format Control: Disable WEBP/AVIF globally or per-tag:

{{ responsive:field_handle webp="false" avif="true" }}

Or in config:

'webp' => false,
'avif' => true,

Gotchas and Tips

Pitfalls

Cache Conflicts:
- If statamic.assets.image_manipulation.cache is true, regenerate images with:
```
php artisan responsive:regenerate
```
- Note: This command is not needed for on-demand generation (cache = false).
Broken Asset References:
- Statamic v6.6+ requires explicit handling of asset reference updates. Ensure your config/statamic/assets.php includes:
```
'update_asset_references' => true,
```
Placeholder Issues:
- Disable placeholders (base64 blobs) for large images:
```
{{ responsive:field_handle placeholder="false" }}
```
- Placeholders are generated asynchronously via jobs. If missing, check the images queue.
Glide Parameter Overrides:
- Prefix Glide params with glide: (e.g., glide:width). Omitting the prefix may cause unexpected behavior.
- Example:
```
{{ responsive:field_handle glide:width="1200" }}  {# Correct #}
{{ responsive:field_handle width="1200" }}       {# Ignored #}
```
Breakpoint Mismatches:
- Ensure breakpoints in the field config match those in responsive-images.php. Defaults to Tailwind’s breakpoints (sm, md, lg, etc.).
- Fix: Reconfigure breakpoints in config/responsive-images.php:
```
'breakpoints' => ['mobile', 'tablet', 'desktop'],
```
GraphQL Argument Naming:
- Replace colons (:) with underscores (_) in GraphQL. Example:
```
responsive(lg_ratio: "16/9")  {# Instead of lg:ratio="16/9" #}
```

Debugging Tips

Check Queues: Run php artisan queue:work to process pending image jobs. Monitor with:
```
php artisan queue:list
php artisan queue:failed
```
Log Generation: Enable debug logging in config/responsive-images.php:
```
'debug' => env('APP_DEBUG', false),
```
Check storage/logs/laravel.log for generation errors.
Asset Existence: Verify assets exist in the container. Use:
```
{{ dump(responsive:field_handle) }}
```
to inspect the generated output.

Extension Points

Custom Dimensions Calculator: Override the default dimension logic by publishing the config and extending:

// config/responsive-images.php
'dimension_calculator' => \App\Services\CustomDimensionCalculator::class,

Modify Generated HTML: Publish the Twig template:
```
php artisan vendor:publish --tag=responsive-images-views
```
Then extend resources/views/vendor/responsive-images/default.blade.php.
Add Custom Formats: Extend the Spatie\ResponsiveImages\ImageFormat class to support additional formats (e.g., JPEG XL).

Prevent Generation for Specific Assets: Use the excluded_containers config or filter assets in a custom job:

// app/Jobs/ProcessResponsiveImage.php
public function handle()
{
    if ($this->asset->container()->handle === 'excluded') {
        return;
    }
    // ... rest of the logic
}

Pro Tips

Art Direction with Multiple Assets: Combine src and ratio per breakpoint for complex layouts:

{{ responsive:field_handle
   ratio="4/3"
   md:src="desktop_asset"
   md:ratio="16/9"
   lg:src="large_desktop_asset"
}}

Fallback for Unsupported Browsers: Use the placeholder parameter to ensure visibility while srcset loads:
```
{{ responsive:field_handle placeholder="true" }}
```

Dynamic Quality: Adjust quality per breakpoint or format:

{{ responsive:field_handle
   quality:webp="80"
   md:quality:webp="90"
   lg:quality:avif="70"
}}

A/B Testing: Use the src breakpoint parameter to swap images dynamically:
```
{{ responsive:field_handle src="variant_a" }}
```
(Toggle variant_a/variant_b via a query string or session.)

Statamic Responsive Images Laravel Package