Joomla 4/5 User Manual

Manual Index

Customising the Smart Search results page

This tutorial explains how to customise the search results page in Smart Search. To achieve this you use the Joomla layout override system. You need to be able to create new files and edit them on your web hosting site using FTP or other tools that are available to you (contact your web host if you need more information).

All file paths are relative to the directory in which Joomla is installed. When looking at the files you need to create, it is assumed that you will create the necessary folders if they don't already exist in each case. The directory default_template refers to the template that is set as the default for your site. Please replace this name with the actual name of the template directory.

For more information on layout overrides, read the following pages:

The Search View (Default Layout)

The default layout search view is divided into three parts: the default layout, the form layout and the results layout.

The default layout (default.php)

This layout is very simple. It just defines the structure around which the search form and the search results are displayed.

To customise the default layout, find the file:


Copy this to:


Make any adjustments you need to structural elements that contain the search form and the search results. This layout is also responsible for loading the default CSS stylesheet for Smart Search which is located in media/com_finder/css/finder.css, so you might want to alter that to load own CSS rules for Smart Search.

The form layout (default_form.php)

This layout defines the code required for the search form to operate correctly. The layout contains significant Mootools-based JavaScript code that should not be altered unless you know what you are doing. The view method getFields includes a number of hidden fields that are required for reliable searching.

The search term is defined by the input field with the name of "q".

To customise the default layout, find the file:


Copy this to:


Make any adjustments you need to the form as required.

The results layout (default_results.php)

This layout produces the list of matching results for the search term.

To customise the default layout, find the file:


Copy this to:


This layout handles pagination and loads sub-layouts for each individual search result.

Customising results for a particular content type

Smart Search can be set up to load a different sub-layout for specific content types. By default each individual search result is rendered using the default_result.php layout. However, if present, for the standard Joomla content types, the following layout files will be loaded instead:

Content type Layout file
Article default_article.php
Category default_category.php
Contact default_contact.php
News feed default_newsfeed.php
Web link default_weblink.php

Custom content types may look for other layout files.

Developer note: The name of the layout file that will be used is defined in the $layout property of the Smart Search plug-in for that content type.