Agent Skills: Hyvä Render Image

Hyvä Render Image

Generate responsive <picture> elements for Hyvä Theme templates using the \Hyva\Theme\ViewModel\Media view model.

When to Use

• Adding images to Hyvä PHTML templates
• Creating responsive images with different sources for mobile/desktop
• Implementing hero banners, product images, or CMS content images
• Optimizing images for Core Web Vitals (LCP, CLS)

Workflow

1. Gather Image Requirements

The user may provide image data in one of these ways:

Option A: Direct values - Ask the user for:

1. Image path(s) - Location in pub/media/ (e.g., wysiwyg/hero.jpg, catalog/product/...)
2. Image dimensions - Width and height in pixels
3. Responsive requirements - Different images for mobile vs desktop?
4. Image purpose - Hero/LCP image (eager loading) or below-fold (lazy loading)?
5. Alt text - Meaningful description for accessibility

Option B: PHP variable - The user provides a variable name (e.g., $imageData, $heroImage). Inform the user of the required array structure documented in references/rendering-images.md under ## Image Configuration Format.

2. Generate the Code

Refer to references/rendering-images.md for the complete API reference, code examples, and all configuration options.

Choose the appropriate pattern:

| Scenario | Pattern to Use | |----------|---------------| | Single image, literal values | Single Image Example | | Single image from variable | Wrap in array: [$imageData] | | Multiple images from variable | Pass directly: $images | | Different images for mobile/desktop | Responsive Images with Media Queries | | Need to style the <picture> wrapper | Picture Element Attributes |

Base template:

<?php
/** @var \Hyva\Theme\ViewModel\Media $mediaViewModel */
$mediaViewModel = $viewModels->require(\Hyva\Theme\ViewModel\Media::class);

echo $mediaViewModel->getResponsivePictureHtml(
    $images,        // Array of image configs (see reference for format)
    $imgAttributes, // Optional: alt, class, loading, fetchpriority
    $pictureAttributes // Optional: class, data-* attributes for <picture>
);

3. Set Loading Strategy

| Image Type | Attributes | |------------|------------| | Hero/LCP (above fold) | 'loading' => 'eager', 'fetchpriority' => 'high' | | Below fold | 'loading' => 'lazy' |

Resources

• references/rendering-images.md - Complete API reference with method signature, all configuration options, code examples, and best practices