Table of Contents & Menu
On this page
Navigation

Custom Sliders

Creating custom sliders is similar to product sliders and involves defining the following XML:

<page>
    <body>
        <referenceContainer name="content">
            <block name="my-slider" template="Hyva_Theme::elements/slider.phtml">
                <arguments>
                    <argument name="title" xsi:type="string">My Slider</argument>
                </arguments>
                <!-- Your Child blocks as slides -->
            </block>
        </referenceContainer>
    </body>
</page>

Once defined, simply add child blocks to serve as individual slides.

Configuration

Option Default Value Type Description
slider_name Layout block name String Slider ID (for unique identification and skiplinks)
title String Slider label and visual heading (required for accessibility)
heading_tag h3 String Visual heading HTML Tag
css_classes my-8 String CSS classes for the slider block
heading_css_classes text-2xl font-medium String CSS classes for the block heading
column_count 1 Number Number of columns to display
slider_css_classes String CSS classes for the slider track
show_heading true Boolean Show the visual heading
show_pager true Boolean Show the slider pager dots

Creating Custom Sliders in a Template

You can create custom sliders directly within your .phtml templates, bypassing XML configuration. These sliders leverage the AlpineJS Snap Slider plugin.

Simply write the HTML markup for a CSS-based slider and initialize it with the AlpineJS plugin. For detailed instructions and examples, refer to the AlpineJS Snap Slider plugin documentation.

Before version 1.4

Deprecated

Everything below is for older versions of Hyvä (before 1.4) and is marked for deprecation.

For Hyvä versions prior to 1.4, a generic slider template is available for rendering custom slider items using PHP.

The recommended approach is to use 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'))
                 ->toHtml()
?>

The slider title can be optionally set using setTitle($title) or setData('title', $title).

An individual slider item is rendered using a dedicated template, for example:

<?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"
   style="padding-top:100%"
   tabindex="-1">
       <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()) ?>"
            loading="lazy"
        >
        </span>
</a>

<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()) ?>
    </a>
</p>

Specifying Slider CSS classes

maybe_purged_tailwind_section_classes

Available since 1.1.8

Set the maybe_purged_tailwind_section_classes property on the slider block to apply CSS classes to the containing slider <section> DOM element.

For example:

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

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

maybe_purged_tailwind_slide_item_classes and max_visible

Available since 1.3.6

Control the CSS classes for the <div> element wrapping each slider item by setting the maybe_purged_tailwind_slide_item_classes property on the slider block. This allows you to manage visible slides at different breakpoints without modifying slider-php.phtml.

Ensure that the slide item width breakpoints in maybe_purged_tailwind_slide_item_classes align with the number of visible items on the largest breakpoint set via max_visible. The default max_visible is 4.

For example:

<?= $slider->getSliderForItems('My_Module::my-item.phtml', $items)
           ->setData('max_visible', 2)
           ->setData('maybe_purged_tailwind_slide_item_classes', 'py-1 md:w-1/2')
           ->toHtml() ?>

If not specified, the default classes py-1 md:w-1/2 lg:w-1/3 xl:w-1/4 are applied.

Maybe purged?

The property name includes maybe_purged to indicate that if the classes are set in layout XML (instead of a .phtml template).
They may not be seen by Tailwind during the compilation, and thus might be missing from the production bundle, unless the XML files are also included in the content path in the Tailwind configuration.

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

Specifying a custom slider template

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

To use a custom template, provide it as the third argument to the getSliderForItems method:

<?=
    $sliderViewModel
        ->getSliderForItems('My_Module::my-item.phtml', $items, 'My_Module::my-slider.phtml')
        ->toHtml()
?>

Implementation details for the curious

While the generic slider template can be configured via layout XML and PHP, using the view model is generally faster and easier. XML configuration is primarily for older installations where the Hyva_Theme module lacks the slider view model and cannot be upgraded.

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

The slider template iterates through all items, assigns each to the child block, and calls toHtml().