The Google Custom Search Plugin

If you intend to produce a lot of content for your site, or are expecting your visitors to have specific questions that they need to find the answers to, then including a search option can greatly improve the site experience. With the Google Custom Search plugin, visitors can use the power of Google's search engine, but limit the search only to your site content. The plugin uses Google Programmable Search Engine, which was previously called Google Custom Search.

Creating a search engine in Google

Before the plugin can be enabled and configured, you will need to create your search engine in Google. To do so, follow these steps:

To begin, head over to the Google Programmable Search Engine homepage and after logging in, click on the blue "Add" button.
On the next screen, enter a name for your search engine in the Name your search engine field. Below it, in the What to search? section, add your website's URL; this ensures your entire site is searched. You can also restrict the search to particular areas of your site if you wish, but generally you'll want the whole site to be available for searches.
On the same screen you can enable the Image search or SafeSearch option, then click the Create button to create the search engine.
The search engine is now created, but we need to grab one important piece of information for later, when we set up the plugin in Publii. Click on the Customize button to be taken to the Overview page.
You don't need to use the code generated by Google, because the plugin inserts the appropriate code on the live site, but you do need the Search engine ID so that the plugin can find your search engine. Click on the Copy icon in the Search engine ID section and save this ID for later.

Note:
Since January 2026, Google no longer allows new search engines to search the entire web, and existing engines lose this option on January 1, 2027. Each search engine can now include up to 50 domains. This doesn't affect the plugin, because it is designed to search your own site only.

The plugin always displays search results in the Results only layout, so the results fit inside your theme's search page. You can still adjust colors and other visual options in the Look and feel section of the Google control panel if you wish.

The Google side of the configuration is now ready, so we can get started with configuring the Google Custom Search plugin in Publii.

Enabling the search area in your theme

In order for the plugin to display the search bar on your site, the theme needs a specific section set aside for it. All official Publii themes, both free and premium, include a section for the search bar, but it is disabled by default. To enable the search area, follow these steps:

Note: If you are using a custom theme, it may not include a section for the search bar. In such cases, you will need to add it to your theme manually; you'll find more information on how to do this in the next section of this guide.

In the Publii app, click on the Theme option in the left-sidebar menu to open the Theme Settings page.
In the second section of this page, titled Custom Settings, click on the Search option to see the search settings for your site.
Enable both options in this section: Search, which enables the search box in the main menu or another area specified by the theme, and Search subpage, which creates a search page where the results of any searches are displayed.
Once enabled, click on the Save Settings option at the bottom of the page to save the changes.

The search area is now enabled, and we can move on to the plugin.

Adding search functionality to a custom theme

If you are using a custom theme that doesn't support search, when opening the plugin configuration you will see a message advising that Your current theme doesn't support a required feature: custom search. In order to use the Google Custom Search plugin, you will need to make some changes to your theme files to add the search box and the search page. This is only required if you are using a custom or modified theme; all official Publii themes, both free and premium, already include this code.

To add the search box to your theme, insert the following code snippet in the theme file where you want the search box to appear, for example in the header. This will render a search input field (and an optional submit button) that visitors can use to search your site.

{{{@customSearchInput}}}

Important:
This shortcode must be placed in a theme file, not within post or page content.

You'll find your theme files at the following location:

Documents ▸ Publii ▸ sites ▸ YOUR_SITE ▸ input ▸ themes ▸ YOUR_THEME

To display the search results, update the search.hbs file (or create it, if your theme doesn't have one) and paste the following code snippet into it:

{{{@customSearchContent}}}

This snippet renders the search form on the results page, the search results themselves and, if needed, the cookie consent notice.

You also need to modify the config.json file (only if your theme does not support search plugins yet) by updating the 'renderer' and 'supportedFeatures' sections with the following flags:

"renderer": {
     "createSearchPage": true
 },
 "supportedFeatures": {
     "searchPage": true,
     "customSearch": true
 },

The search is now configured, and you can move on to enabling and configuring the plugin. Note that if the previous steps have not been followed correctly, you will see an error message at the top of the plugin configuration screen advising you that the theme does not currently support the search function.

Enabling the plugin

To activate the plugin, open the Tools & Plugins section of the Publii app via the left menu to see a list of installed plugins. Click on the switcher button in the bottom-left of the Google Custom Search box in this list to enable the plugin.

You'll need to enter at least the Search engine ID, so click on the Google Custom Search box again, anywhere except on the switcher button, to open the plugin settings page.

Google Custom Search plugin options

The only option required for the plugin to work is the Search engine ID. The other options can be changed or enabled depending on your preferences:

Search configuration

Search engine ID - Enter your Google Search engine ID in this field; this is required for the plugin to work. If the ID is missing or invalid, the plugin won't load Google's search script, and a notice about it will be displayed on the search page in the Publii preview.
Search parameter - The name of the URL parameter that holds the search phrase, for example ?q=publii. By default this is set to 'q' and in most cases it should be left as it is. If you change it, the plugin passes the new name to Google automatically, so you don't need to change anything in the Google control panel. Only letters, numbers, hyphens and underscores are allowed; if the field contains anything else, the plugin falls back to 'q'.

Theme integration

Input placeholder - Text entered in this field will be used as the placeholder text in the search field before the user starts typing. It is also used as the field's accessible label for screen readers.
Autofocus - If enabled, the browser will focus on the search field when the page loads, so users can begin typing immediately.
Submit button - If enabled, a submit button will be displayed in the search box for users to click to start the search. The second option in this section displays the submit button on the search results page as well. Please note that custom themes may require additional CSS styling to make sure the button displays properly.
Submit button label - Sets the text displayed on the submit button; by default this is set to 'Submit'.

Cookie Banner integration

Cookie Banner integration - Enabling this option connects the plugin with the built-in Publii cookie banner, so Google's search script is loaded only after the visitor consents to cookies.
Cookie Group ID - This option only becomes available when the Cookie Banner integration option is enabled. Here, you can specify the cookie group the Google script should be assigned to. Make sure to add this group to the GDPR section of the site settings; you can find instructions on how to do this in the GDPR section of this documentation. The ID can contain only letters, numbers, hyphens and underscores. If it's empty or invalid, the plugin won't load Google's search script, and a notice about it will be displayed on the search page in the Publii preview.
Fallback message - Sets the message displayed on the search page when the visitor has not consented to Google's cookies. By default, it tells visitors that search results are disabled and that they can change their cookie preferences in the cookie banner.