Skip to content

Custom Sliders

Hyvä includes a generic slider template that can be used to render custom slider items with PHP.

The easiest way to render the slider is through the slider view model:

<?php declare(strict_types=1);

/** @var \Magento\Framework\View\Element\Template $block */
/** @var \Magento\Framework\Escaper $escaper */
/** @var \Hyva\Theme\Model\ViewModelRegistry $viewModels */
/** @var \Hyva\Theme\ViewModel\Slider $sliderViewModel */

$sliderViewModel = $viewModels->require(\Hyva\Theme\ViewModel\Slider::class);
$itemsTemplate   = 'Example_Module::slider-item.phtml';
$items           = $block->getSomeItems(); // a collection or array of items to render

 $sliderViewModel->getSliderForItems($itemsTemplate, $items)
                 ->setData('title', __('Some Items'))

Setting the title for the slider with setTitle($title) or setData('title', $title) is optional.

The slider items template to render an individual item looks something like the following:

<?php declare(strict_types=1);

/** @var \Magento\Framework\View\Element\Template $block */
/** @var \Magento\Framework\Escaper $escaper */
/** @var \Hyva\Theme\Model\ViewModelRegistry $viewModels */

// The item to render is set on the block before the template is rendered:

/** @var \Magento\Catalog\Model\Product $item */
$item = $block->getData('item');

<a href="<?= $escaper->escapeHtmlAttr($item->getUrl())?>"
   class="relative flex items-center bg-white"
       <span class="absolute top-0 left-0 flex flex-wrap content-center w-full h-full p-2
                    overflow-hidden align-center hover:shadow-sm">
       <img class="self-center w-full h-auto"
            src="<?= $escaper->escapeHtmlAttr($item->getImage()) ?>"
            alt="<?= $escaper->escapeHtmlAttr($item->getName()) ?>"

<p class="flex items-center justify-center px-1 pt-3 text-primary">
    <a class="truncate" href="<?= $escaper->escapeHtmlAttr($item->getUrl()) ?>">
        <?= $escaper->escapeHtml($item->getName()) ?>

Specifying Slider CSS classes

Since release 1.1.8 is possible to specify the CSS classes on the containing slider <section> DOM element by setting the maybe_purged_tailwind_section_classes property on the slider block.

For example:

<?= $slider->getSliderForItems('My_Module::my-item.phtml', $items)
           ->setData('maybe_purged_tailwind_section_classes', 'text-gray-700 body-font')
           ->toHtml() ?>

The property name includes maybe_purged to indicate that if the classes are set in layout XML (instead of a .phtml template), they will not be seen by Tailwind during the compilation, and might be missing from the production bundle.

Usually they will be set in a .phtml file like in the above example though, so likely this will not be an issue.

If no classes are specified, the default my-12 text-gray-700 body-font are used.

Implementation details for the curious

The generic slider template doesn’t have to be used with the view model - it is also possible to configure it with layout XML and PHP.

That said, it is faster and easier to use the view model. Configuring the slider with layout XML should only be considered on old installations where the Hyva_Theme module doesn’t contain the slider view model yet and can’t be upgraded for some reason.

The default slider template is Magento_Theme/templates/elements/slider-php.phtml.

(The template is named slider-php because in future a generic slider that requests items through GraphQL and renders them client side might be added, too.)

The slider view model method getSliderForItems can take an optional third argument to override the default slider template if needed.

The slider expects a child block to with the alias slider.item.template to render the items.

The slider template iterates over all items, assigns the current item to the child block, and calls toHtml().