Developer docs

How to Add Google Custom Search to Ghost

Add search functionality to your Ghost publication and allow your readers to find exactly what they are looking for


Adding search to your Ghost publication gives your readers an additional way to navigate your content and improves engagement. It’s possible to add a sensible search function using the free Google Custom Search tool.

This is possible using the Handlebars theme layer - by using the code provided by Google Custom Search in your theme files. This tutorial will show you how to implement site search on your Ghost publication.

If you’re looking for a free tool to add site search then this is an ideal solution. However it’s important to note that it does come with some limitations with search functionality, custom styles and ads.

Create a new search engine in the Google Custom Search tool

Login to the Google Custom Search tool using Google credentials and create a new search engine. Enter the domain for your Ghost site:

Copy the code provided

Once you’ve entered your domain and any other custom settings required (useful if you want to only search certain parts of your site, or exclude pages), grab the code for your new search function:

Add the code to your theme files

This code can be pasted any where in Ghost depending on how you’d like to render your search box - this could be in your posts, on specific pages or across your whole site.

Open your theme files in your code editor of choice and find the best spot for your search bar. For the purposes of this example, we’re going to put the code into the index.hbs, directly below the header and above the main content area:

It’s a good idea to make one small modification to the code provided by the Google Custom Search tool, which is to add a <div> around <gcse:search></gcse:search> so that you can add some custom CSS later if required.

The Google Custom Search tool gives you plenty of customisation options within the dashboard once you have created your search engine. It’s advisable to spend some time navigating around all of the options available to you so that you understand the full capabilities and limitations of using this tool to implement search on your Ghost publication.

You can style the way the search bar and the results looks, and add or remove the Google branding. There are also several options to customise the behaviour of your search functionality. The tool gives a preview so that you can see the results as you make adjustments and you can come back to this any time and update it.

Update your active theme

By now you should have added the code snippet to your theme files and started customising the behaviour and style of your search engine. Now it’s time to give this thing a test run.

Save your updated theme files and upload the .zip file in the design menu in Ghost Admin. You should now be able to see the search bar on your site!

Here’s an example of what an implementation of Google Custom Search looks like on Coding Horror:

Further customisation

Since we’re inserting Google’s tool via a script, there are two ways that you can adjust the way it appears on your site. First of all you can go back into the customisation menu on the Google Custom Search dashboard and try different themes or tweak the settings. Hit refresh and you’ll be able to see these updates in real time on your site.

Secondly, you can style the search bar yourself with HTML and CSS. Since we added a <div> to the code earlier, you can add some custom CSS to the screen.css file in your theme. For example:

.gse-searchbox {
    display: flex;
    justify-content: center;
    align-items: center;
    margin: 0 auto;
    max-width: 400px;

The rest is up to you! Always remember to update the active theme in Ghost Admin each time you are ready to ship changes to your CSS files 🔧


You’ve completed the tutorial and hopefully deployed a search box on your Ghost publication, powered by Google’s custom search tool. Your search bar can be added to any post or page on your site repeating the same process and adding the code into the relevant Handlebars template files. Don’t forget you can use the Handlebars documentation anytime to learn more about themes!