Hyva Render Media 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:

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

Resources

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

<!-- Copyright © Hyvä Themes https://hyva.io. All rights reserved. Licensed under OSL 3.0 -->

Rendering Responsive Images in Hyvä Templates

The Hyvä Theme provides the \Hyva\Theme\ViewModel\Media view model for rendering responsive images using the HTML <picture> element. This view model generates semantic markup with <source> elements for different screen sizes and image formats, enabling art direction and format selection for optimal performance.

Method Signature

\Hyva\Theme\ViewModel\Media::getResponsivePictureHtml(
    array $images,
    array $imgAttributes = [],
    array $pictureAttributes = []
): string

Parameters:

Image configuration keys:

Image Configuration Format

Image data can be provided as literal values or stored in PHP variables. The $images parameter expects an array of image configuration arrays.

Single image config structure:

$imageData = [
    'path' => 'relative/path/in/pub/media/image.jpg',  // Required
    'width' => 800,                                      // Required
    'height' => 600,                                     // Required
    'media' => '(min-width: 768px)',                    // Optional: CSS media query
    'fallback' => true                                   // Optional: use as <img> fallback
];

Passing to the method:

// Single image config must be wrapped in an array
echo $mediaViewModel->getResponsivePictureHtml([$imageData], $imgAttributes);

// Multiple image configs are already an array
echo $mediaViewModel->getResponsivePictureHtml($images, $imgAttributes);

Single Image Example

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

$imageConfig = [
    [
        'path' => 'catalog/product/w/b/wb01-blue-0.jpg',
        'width' => 400,
        'height' => 500
    ]
];

echo $mediaViewModel->getResponsivePictureHtml($imageConfig);

Responsive Images with Media Queries

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

// Desktop image: wide landscape format for large screens
$desktopImage = [
    'path' => 'wysiwyg/homepage-main-hero.jpg',
    'width' => 1920,
    'height' => 600,
    'media' => '(min-width: 768px)',
    'fallback' => true
];

// Mobile image: taller portrait format for small screens
$mobileImage = [
    'path' => 'wysiwyg/homepage-mobile-hero.jpg',
    'width' => 768,
    'height' => 800,
    'media' => '(max-width: 767px)'
];

$imgAttributes = [
    'alt' => 'Summer Collection',
    'class' => 'w-full h-auto',
    'loading' => 'eager',
    'fetchpriority' => 'high'
];

echo $mediaViewModel->getResponsivePictureHtml(
    [$desktopImage, $mobileImage],
    $imgAttributes
);

Picture Element Attributes

$pictureAttributes = [
    'class' => 'hero-banner aspect-video',
    'data-testid' => 'homepage-hero'
];

echo $mediaViewModel->getResponsivePictureHtml(
    $imageConfig,
    $imgAttributes,
    $pictureAttributes
);

Common Image Attributes

Best Practices

1. Always specify width and height - Prevents Cumulative Layout Shift (CLS) 2. Use `loading="lazy"` - For images below the fold 3. Use `loading="eager"` + `fetchpriority="high"` - For LCP (Largest Contentful Paint) images 4. Provide meaningful alt text - Required for accessibility 5. Use media queries for art direction - Different crops for mobile vs desktop 6. Mark one image as `fallback` - For browsers without <picture> support

Common Mistakes

1. Forgetting to wrap a single image in an array

   // Wrong - passing image config directly
   echo $mediaViewModel->getResponsivePictureHtml($imageData, $imgAttributes);

   // Correct - wrap in array
   echo $mediaViewModel->getResponsivePictureHtml([$imageData], $imgAttributes);

2. Using absolute paths instead of relative `pub/media/` paths

   // Wrong - absolute or full URL paths
   'path' => '/pub/media/wysiwyg/hero.jpg'
   'path' => 'https://example.com/media/wysiwyg/hero.jpg'

   // Correct - relative to pub/media/
   'path' => 'wysiwyg/hero.jpg'

3. Missing width and height causing layout shift (CLS)

   // Wrong - missing dimensions
   $imageConfig = [['path' => 'wysiwyg/hero.jpg']];

   // Correct - always specify dimensions
   $imageConfig = [[
       'path' => 'wysiwyg/hero.jpg',
       'width' => 1920,
       'height' => 600
   ]];

4. Using `loading="lazy"` on above-the-fold LCP images

   // Wrong - lazy loading hero images delays LCP
   'loading' => 'lazy'

   // Correct - eager load with high priority for hero/LCP images
   'loading' => 'eager',
   'fetchpriority' => 'high'

5. Overlapping media queries in responsive images

   // Wrong - both match at 768px
   'media' => '(min-width: 768px)'  // desktop
   'media' => '(max-width: 768px)'  // mobile

   // Correct - no overlap
   'media' => '(min-width: 768px)'  // desktop
   'media' => '(max-width: 767px)'  // mobile