How to customize template

This page explains how to customize a template for your product finder. Create a new .phtml file in the theme your store uses, in app/design/frontend/<Vendor>/<theme>/Mirasvit_Finder/templates/finder/, then select it in the finder's Template field (Catalog -> Product Finder, section Appearance). The field lists every file in that folder by its file name. To change the default design instead, name your file horizontal.phtml or vertical.phtml: it then replaces the template of the same name.

Luma and Hyvä use the same templates, so one override in your theme covers both. Let's explore the default Horizontal template and analyze its parts. It is located in:

vendor/mirasvit/module-finder/src/Finder/view/frontend/templates/finder/horizontal.phtml

Note

If you customized a finder or filter template before version 1.2.0, check Templates customized before version 1.2.0: some of those copies stop working after the upgrade.

1. Data retrieval

$finder   = $block->getFinder();
$filters  = $block->getFilters();
$finderId = (int)$finder->getId();

The code retrieves the finder object (the main search block), an array of filters (the list of filters to be displayed to the user) and the finder ID. This part of code should be used without any changes.

2. Main HTML structure

<section class="mst-finder__finder mst-finder__finder-horizontal _col-<?= $block->escapeHtmlAttr(count($filters)) ?> card" data-finder="<?= $block->escapeHtmlAttr($finderId) ?>" role="search" aria-labelledby="finder-<?= $block->escapeHtmlAttr($finderId) ?>-title">
    <header class="mst-finder__finder-header">
        <h3 id="finder-<?= $block->escapeHtmlAttr($finderId) ?>-title"><?= $block->escapeHtml($finder->getBlockTitle()) ?></h3>
    </header>

    <?php if ($finder->getBlockDescription()): ?>
    <div class="mst-finder__finder-description">
        <p><?= $block->escapeHtml($finder->getBlockDescription()) ?></p>
    </div>
    <?php endif; ?>

A container is created with classes for styling and a column count equal to the number of filters. The finder's title is displayed in the header, followed by the finder description when one is set. Keep the data-finder attribute: the finder script uses it to find the block.

3. Rendering filters

<div class="mst-finder__finder-filters" role="form" aria-label="<?= $block->escapeHtmlAttr(__('Product search filters')) ?>">
    <?php foreach ($filters as $filter): ?>
        <?= /* @noEscape */ $block->getFilterHtml($filter) ?>
    <?php endforeach ?>
</div>

For each filter, the $block->getFilterHtml($filter) method is called, which generates the HTML for that specific filter (a dropdown or a label filter).

4. Control buttons

<div class="mst-finder__finder-footer">
    <button type="button" class="action btn btn-secondary" data-action-reset aria-label="<?= $block->escapeHtmlAttr(__('Reset all filters')) ?>"><?= $block->escapeHtml(__('Reset')) ?></button>
    <button type="button" class="action primary btn btn-primary" data-action-find aria-label="<?= $block->escapeHtmlAttr(__('Find products with selected filters')) ?>"><?= $block->escapeHtml(__('Find')) ?></button>
</div>

At the bottom of the block, there are two buttons: Reset (to clear filters) and Find (to search for products based on the selected filters). The data-action-reset and data-action-find attributes connect them to the finder script, so keep them on your buttons.

5. Inserting JS

    <?= /* @noEscape */ $block->getJsHtml() ?>
</section>

This renders Mirasvit_Finder::js.phtml: the finder settings as a JSON block and the Mirasvit_Finder/js/finder-standalone.js script. The script is the same on Luma and Hyvä and needs neither jQuery, RequireJS nor Alpine.js, so the template carries no theme-specific code. Keep this call in your template, preferably inside the <section> as above: without it the finder does not respond at all.

Templates customized before version 1.2.0

Version 1.2.0 replaced the finder's jQuery widgets (Luma) and Alpine.js components (Hyvä) with one script, and the Hyvä templates moved from mirasvit/module-finder-hyva into the extension. A template copied from an earlier version still renders, but it may stop working:

Your copy	What happens after the upgrade	What to do
Luma finder template (finder/horizontal.phtml, finder/vertical.phtml, or your own file based on them)	The finder works. The browser console shows Script error for "Mirasvit_Finder/js/chosen.jquery" and a 404 for chosen.jquery.js.	Delete the <link ... getCssAsset() ...> line and the <script> block that loads Mirasvit_Finder/js/chosen.jquery at the end of the file.
Hyvä finder template from mirasvit/module-finder-hyva, copied to Mirasvit_Finder/templates/finder/ in your theme	The finder looks normal and its options load, but Find and Reset do nothing. The console shows createFinderComponent is not defined.	Copy the new template from vendor/mirasvit/module-finder/src/Finder/view/frontend/templates/finder/ and apply your changes to it again.
Any template at a Hyva_MirasvitFinder/templates/... path in your theme	It is no longer read. The store shows the default template, without your changes.	Copy the new template to Mirasvit_Finder/templates/... in your theme and apply your changes again.
Filter template (filter/dropdown.phtml, filter/label.phtml) from either theme	The finder breaks. On Luma, Find opens a broken results URL that loses the filter names, and the console shows 404s for dropdownFilter.js and labelFilter.js. On Hyvä, the filters stop responding.	Delete your copy, or copy the new one from vendor/mirasvit/module-finder/src/Finder/view/frontend/templates/filter/ and apply your changes again.

When you rework an old copy, keep the data-finder, data-action-find and data-action-reset attributes and the getJsHtml() call shown above. Without them the finder does not respond, and no error is shown.