Table of Contents & Menu
On this page
Navigation

Product Sliders

As of Hyvä 1.1.9, product sliders are server-side rendered (SSR). This prevents layout shifts and performance issues common with client-side rendering. SSR sliders also support features like swatches and "Add to Cart" functionality.

Backward Compatibility

The old GraphQL-based client-side slider template (Magento_Theme/templates/elements/slider.phtml) is deprecated but remains available for backward compatibility.

Page Builder

These SSR product sliders are distinct from Adobe Commerce Page Builder sliders.

How to Use

To use a product slider, add the hyva_product_slider layout handle to your page. Then, declare a block using the Magento_Catalog::product/slider/product-slider.phtml template and configure it with the arguments below.

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <update handle="hyva_product_slider" />
    <body>
        <referenceContainer name="content">
            <block name="my-slider" template="Magento_Catalog::product/slider/product-slider.phtml">
                <arguments>
                    <argument name="title" xsi:type="string" translate="true">My Awesome Slider</argument>
                    <argument name="category_ids" xsi:type="string">25</argument>
                    <argument name="page_size" xsi:type="number">8</argument>
                </arguments>
            </block>
        </referenceContainer>
    </body>
</page>

Configuration

Configure the slider block using the following arguments:

Slider Display Options

Option Type Default Description
title String Required. Slider title and accessible label.
heading_tag String h3 HTML tag for the visual heading.
show_heading Boolean true Display the visual heading.
heading_css_classes String text-2xl font-medium CSS classes for the heading.
css_classes String my-8 CSS classes for the main slider container.
slider_css_classes String CSS classes for the slider track.
column_count Number 4 Number of slides visible at the largest breakpoint.
show_pager Boolean true Display pager dots below the slider.
slider_name String Block Name Unique ID for the slider (used for skiplink).

Product Content Options

Option Type Default Description
hide_rating_summary Boolean false Hide star rating summary.
hide_details Boolean false Hide product details (e.g., swatches).

Product Selection & Filtering

type

(Type: string, Default: none)

Displays products based on their relation to the current context:

  • related: Shows products related to the main product on a product detail page.
  • upsell: Shows upsell products on a product detail page.
  • crosssell: Shows cross-sell products for items in the cart. Can be used on any page.

Example: 

<argument name="type" xsi:type="string">crosssell</argument>

category_ids

(Type: string, Default: none)

A comma-separated list of category IDs to display products from.

Example: 

<argument name="category_ids" xsi:type="string">25,26</argument>

include_child_category_products

(Type: boolean, Default: false, Available since 1.1.18)

When category_ids is a single anchor category, setting this to true includes products from its child categories. No effect if multiple categories are specified or the category is not an anchor.

Example: 

<argument name="include_child_category_products" xsi:type="boolean">true</argument>

product_skus

(Type: string, Default: none, Available since 1.1.10)

A comma-separated list of product SKUs to display. SKUs containing commas are not supported.

Example: 

<argument name="product_skus" xsi:type="string">MH01,MH02,MH03</argument>

price_from / price_to

(Type: string, Default: none)

Filters products by a specified price range.

Example: 

<argument name="price_from" xsi:type="string">20</argument>
<argument name="price_to" xsi:type="string">100</argument>

additional_filters

(Type: array, Default: none)

Applies custom filter criteria using SearchCriteria filter syntax. The default conditionType is eq.

Possible conditionType values: eq, neq, like, in, nin, notnull, null, from, to, gt, lt, gteq, lteq, moreq, finset, regexp.

Example (filtering by color attribute): 

<argument name="additional_filters" xsi:type="array">
    <item name="color-filter" xsi:type="array">
        <item name="field" xsi:type="string">color</item>
        <item name="value" xsi:type="array">
            <item name="blue" xsi:type="string">24</item>
            <item name="red" xsi:type="string">28</item>
        </item>
        <item name="conditionType" xsi:type="string">in</item>
    </item>
</argument>

page_size

(Type: number, Default: 8)

Maximum number of products to display in the slider.

Limitation for crosssell sliders

The page_size argument does not work for crosssell sliders. To change the number of cross-sell items, customize the maxCrosssellItemCount constructor argument of \Hyva\Theme\ViewModel\ProductList via di.xml.

Example: 

<argument name="page_size" xsi:type="number">12</argument>

Product Sorting

sort_attribute

(Type: string, Default: position)

The product attribute to sort slider items by.

Example: 

<argument name="sort_attribute" xsi:type="string">created_at</argument>

sort_direction

(Type: string, Default: ASC)

Sorting direction: ASC (ascending) or DESC (descending).

Example: 

<argument name="sort_direction" xsi:type="string">DESC</argument>

Full Example

This example shows a slider with red, yellow, and orange products from categories 5 and 6, priced between 30 and 100, sorted by price.

Note: Attribute option and category IDs may differ on your Magento instance.

<block name="redish-products-slider" template="Magento_Catalog::product/slider/product-slider.phtml">
    <arguments>
        <argument name="title" xsi:type="string" translate="true">Our favorites in Red</argument>
        <argument name="category_ids" xsi:type="string">5,6</argument>
        <argument name="additional_filters" xsi:type="array">
            <item name="color-filter" xsi:type="array">
                <item name="field" xsi:type="string">color</item>
                <item name="value" xsi:type="array">
                    <item name="orange" xsi:type="string">56</item>
                    <item name="red" xsi:type="string">58</item>
                    <item name="yellow" xsi:type="string">60</item>
                </item>
                <item name="conditionType" xsi:type="string">in</item>
            </item>
        </argument>
        <argument name="price_from" xsi:type="string">30</argument>
        <argument name="price_to" xsi:type="string">100</argument>
        <argument name="sort_attribute" xsi:type="string">price</argument>
        <argument name="sort_direction" xsi:type="string">DESC</argument>
        <argument name="hide_rating_summary" xsi:type="boolean">true</argument>
        <argument name="hide_details" xsi:type="boolean">true</argument>
    </arguments>
</block>

Legacy Configuration (pre-1.4.0)

The following arguments are deprecated since Hyvä 1.4.0 and should no longer be used:

  • item_template: Removed. Product item rendering is now consistently handled by Magento_Catalog/templates/product/list/item.phtml.
  • container_template: Removed.
  • max_visible: Renamed to column_count.
  • maybe_purged_tailwind_slide_item_classes: Renamed to css_classes, which applies classes to the main slider block. The number of visible items is now controlled by column_count.