Custom Search

Control Panel

This page discusses how you can customize the look and feel of your search box and search results using the control panel. If you want to implement the design of your search engine using the context file, see the "Designing the Look and Feel with XML page".

Contents

Overview

You can change both the search box and the search results of your custom search engine in either the control panel or the XML context file. If you have a handful of search engines, managing and customizing them with the control panel is fairly simple. Just navigate to the the Look and feel tab, select a style, design the components, click Save, and you are good to go. This page tells you how to do all that. However, if you are creating and managing a large number of search engines, even that simple procedure—when repeated across multiple search engines—gets tedious. In such cases, working with XML would be better. If you decide to use XML, read this page first to get an idea of how things generally work; afterwards, read the Designing the Look and Feel with XML page to learn about the XML elements and attributes.

If you are not sure whether you should just use the control panel or use the XML format, see The Basics page, which discusses the benefits and challenges of each format.

Note: Before you start designing the look and feel of your custom search engine, read the Guidelines for implementing Google Custom Search. It's a short document that tells you how you should handle Google branding and attribution.

If you do not want ads in your search results page, upgrade to the Site Search edition. To learn more about how you can upgrade your search engine, see the Choosing the Right Format section in The Basics page.

Back to top

Hosting the Results using the Search Element

A Search element is an object that you can embed in your webpage, which allows extensive customization. It can show the search box and search results, either together in the same webpage that the reader is viewing or in different webpages.

Example of a search element

Note: Search element, when paired with a compact layout, works well on mobile devices.

You can also take advantage of the Javascript Developer's Guide to further customize the search UI. If you do not want to tinker with Javascript, the Search element can still provide you with most customization choices. For example, you can select among six layouts for your results page, or you can download the CSS and make changes to it.

Google Custom Search no longer supports the iframe hosting option. We recommend the "Two page" or "Results only" layouts in Search element as the new options. Check out our blog post for more information.

Back to top

Designing Individual Components of the Search UI

You can customize the look and feel of your search engine by doing the following:

  1. In the Look and feel tab of the control panel, select a search element layout.
  2. Under Choose or customize a style section, select a style.
  3. If you want to customize the style, do the following (otherwise, skip to the next step):
    1. Click the Customize button.

    2. Select the appropriate controls from the style tabs.

    3. Define the new values.

      If you change your mind, you can always revert back to the default values by clicking Reset style. Experiment with the values while previewing the changes.

    4. If you've enabled image search, select the layout you want.
  4. Click Save.
  5. Implement the design in your website.

Back to top

The Customizable Components

The components that you can customize depends on the selected Element layout of your search engine. For example, the control panel lets you add a logo only for search engines that are hosted by Google; you cannot add a logo to search engines using other hosting options.

You can define the following components using the control panel:

Setting the Search Element Layout

You have the option to customize how your search UI is laid out on the webpage. You can place the search box and the results section in the same column or display them in separately columns with the search box in one column and the results section in another column or even in another page.

Your layout options are (click the links to see demos):

Option Description
Full-width v1 | v2 The search box and the search results section take up the entire width of the page or the column where you have inserted the Search element.
Compact v1 | v2 Like the full-width option, this takes up the the entire width of the page or column, but the results section shows fewer results, so it takes up less vertical space when expanded in the webpage.

Tip: This option is optimized for smartphones and mobile devices.

Two Column v1 | v2 The search box and the search results section are in different columns or sections of your webpage. To close the search results section, the user clicks on the X icon next to the search box.
Two Page
Simple: v1 | v2
Multiple search boxes/results sections: v2
The search box and the search results section are placed in two different webpages.

Note: The search results section also contains a search box. Users can submit queries in the search results page directly.

Results Only
Search via URL: v1 | v2
Search via search box: v1 | v2
Search results are placed in one of your webpages, and the search results page does not contain a search box. Use your own search box to submit the search query.

Note: To use your own search box for a standard free custom search engine, you must use the Google branding. If your site uses Google Site Search, branding is optional.

Demo: How to customize branding options

Google-Hosted
Current window: v1 | v2
New window: v1 | v2
The search box is placed on one of your webpages. The search results are displayed on a Google-hosted webpage, which can be opened either in the same window or in a new window.

Back to top

Designing the Search Box

You can insert the search box anywhere within the HTML body of your webpage, although—by convention—search boxes are placed at the top (or close to the top) of webpages, as in the following example:

Figure 1: Webpage with the search box positioned at the top.

Example of a webpage with a search  box

To create and design a search box, do the following:

  1. Customize the search box.
  2. Optional. Enable autocompletion.
  3. Implement the search box in your webpages.

Back to top

Customizing the Search Box for the Search Element

You can customize the search box by doing the following in the style tabs:

  • Change the colors:
    1. Select the Search Controls tab.
    2. Set the values for the colors of the search box:
      • Search input: Border color - the color of the border around the input field for search queries.
      • Search button: Border color - the color of the border around the search button. The thin lines of the border might not be apparent if the color is similar to that of the button.
      • Search button: Background color - the color of the search button.
    3. Click Save.
  • Change the font style for the search button (and the rest of the element):
    1. Select the Global styles tab.
    2. In the Text drop-down list, select the font family.

      The setting changes the font of not just the text in the search button, but also the text in the entire element, including the refinement tab and the result snippets.

    3. Click Save.

The preview section below the style tabs shows the changes you made in the settings.

Back to top

Enabling Autocompletion

Autocompletion offers query options to your users as they enter their search queries on your search box. It is similar to the optional queries that you see on Google search.

Figure 2: Typing just a few characters in the search box brings up a drop-down list that provides options for different search queries.

Typing "p-u-e-r" in a custom search engine for a travel site brings up a drop-down list with options for "puerto rico", "puerto vallarta hotels", "puerto vallarta vacations" and so on.

Custom Search tailors autocompletion specifically to your search engine. It uses a different algorithm that draws from multiple sources, including queries to your search engine, as well as keywords and phrases extracted from the content of websites that your search engine covers.

Because the autocompleted queries are based—in part—on the specific content of the webpages covered by your search engine, Custom Search does not generate autocompletions for search engines that search the entire web. In other words, only search engines that search included sites—a predetermined collection of websites—can have autocompleted queries. You can set the coverage of your search engine in Sites tab of the the control panel. For more information, see Getting Started.

Unlike the other settings described in this page, autocompletions is not in the Look and Feel tab, but in the Autocompletion section of the control panel.

To enable autocompletions, do the following:

  1. In the control panel, select the Autocompletion tab.
  2. Select Enable autocompletions check box..
  3. Click Save Changes.

    Note: Because the autocompleted queries are generated for each search engine, it takes a few hours before autocompletion starts appearing in your search engine.

  4. If you are enabling autocompletions in an existing search engine for the first time, you have to remove the code snippet for the search box that you had inserted in your webpage. Replace it with the new one generated in the Get code tab. For more detailed instructions, see the Implementing the Design in Your Website section.

Back to top

Designing the Results

You can change the following components of the the results page:

The Background Color

To change the background color of your entire results, do the following in the style tabs:

  1. Select the Global styles tab.
  2. In the Element styling: Background color selector, pick the color. Alternatively, you can enter the color value in the text box.
  3. Click Save.

You can also change the color of the border that surrounds the entire element by picking the Element styling: Border color selector or typing the color value in the text box.

The Individual Results

If you want to visually delineate individual results or highlight results that are being selected by users, you can define the borders and background for individual results.

Figure 3: Results with individual results delineated and individual result that is highlighted on mouseover.

Results with individual results delineatedResults with highligted result

To change the colors of individual results, do the following in the style tabs:

  1. Select the Results tab.
  2. Define the following values:
    • Results (normal state) styling - Each individual result forms a unit of title, result snippet, and link. This setting controls the color for the individual results. If you want to change the background for all the results, see The background Color section.
      • Border color - the border of each individual result.
      • Background color - the background color of each individual result.
    • Results (hover state) styling - The set of definitions controls the color of the an individual result when the mouse cursor hovers over it.
      • Border color - the border of the result.
      • Background color - the background of the result.
  3. Click Save.

Back to top

Image Search Results

Three layouts are available for image search results: Classic, Column, and Popup.

Google Custom Search image search results layout options

The Font Type

To change the font style of the text in your results, do the following in the style tabs:

  1. Select the Global styles tab.
  2. In the Text drop-down list, select the font family.

    The setting changes the font for the entire element, including the search button, the refinement tabs, and the result snippets.

  3. Click Save.

Back to top

The Text Colors

To change the colors of the text in your results, do the following in the style tabs:

  1. Select the Results tab.
  2. Define the following values:
    • Title text colors - this set of definitions controls the colors for the title of the results snippets. The title is the first line of each result.
        • Link color - the title of the result snippet.
        • Visited color - the title after it had been clicked by the user.
        • Hover color - the title when the user hovers the mouse over the link.
        • Active color - the title when the user clicks on the link.
      • Snippet text color - the body of the results snippets. This is the text that provides a small sample of the content of the webpage.
      • URL text color - URL at the bottom of each result snippet.
    • Click Save.

    Back to top

    The Refinement Tabs

    If you have created refinement labels in your search engine, the labels appear as tabs in the Search element. You can use the control panel to change the colors of the refinement tabs.

    To customize the refinements tab, go to the style tabs and do the following:

    1. Select the Search Controls tab.
    2. Set the colors for the refinement tabs:
      • Refinement tab (normal state) - the set of controls for the refinement labels that are not in focus.
        • Border color - the color of the border around the tabs that are not currently selected. The thin line might not be apparent if the color of the border is similar to the color of the background.
        • Background color - the color of tabs that are not currently selected.
      • Refinement tab (selected state): the set of controls for the refinement label that the user has just selected by clicking. The tab that the user has clicked most recently takes the selected state.
        • Border color - the color of the border around the tab that is currently selected.
        • Background color - the color of the tab that is currently selected.
    3. Click Save.

    Back to top

    Promotions

    If you have created promotions in your search engine, you can change their look and feel in the style tabs. Promotions are a special type of search results that you create.

    To customize your promotions, go to the style tabs and do the following:

    1. Select the Promotions tab.
    2. Define the following values:
      • Title text colors - this set of definitions controls the colors for the title of the promotion results.
        • Visited color - the title after it had been clicked by the user.
        • Hover color - For element only. The title when the user hovers the mouse over the link.
        • Active color -For element only. The title when the user clicks on the link.
      • Snippet text color - the description of the promotion. If your promotion does not have a description, the setting changes nothing.
      • URL text color - the URL at the bottom of each promotion.
      • Promotion styling -For element only.
        • Border color - the border around the promotion result.
        • Background color - the background color of the promotion result.
    3. Click Save.

    The Logo (Google-Hosted Only)

    If you are letting Google host your results page, you can choose to include a logo or small image right next to the search box in the search results page. The image has to be a .jpg, .png, or .gif file hosted on a website (your own or from a website that does not have copyright restrictions). You have the option of associating a URL with the image, turning it into a clickable image.

    The following is an example of results page with a logo.

    Figure 4: Search box with an image

    To add or change a logo in your Google-hosted results page, do the following in the style tabs:

    1. Select the Logo tab.
    2. Define the following values:
      • Logo URL - The location of the image. The URL must point to an image file, not a webpage (HMTL file) with an image. The image can be in JPG, PNG, or GIF that does not exceed 100 pixels in height and 100 pixels in width.
      • Logo link - Optional. If you want the logo to link to a webpage (your homepage, for example), type the URL.
      • Logo height - The default value is 100. If your image is larger than 100 x 100 pixels, Custom Search automatically resizes it.
    3. Click Save.

    Back to top

    Customizing the Search Element Further

    If you want to further customize the look and feel of your element, you can change the CSS by doing the following:

    1. Go to the Get code tab.
    2. Under the Want to do more customization section, download the CSS by clicking the CSS source file link.
    3. Copy the contents of the page that appears and paste it in a text editor.
    4. After you make changes, insert the updated CSS code in the CSS section of the Search element code in your webpage.

      Note: CSS hover effects require a supported doctype such as <!DOCTYPE html>.

    Back to top

    Previewing Your Search Engine

    If you enter a query and click Search, you can preview the results, including the refinements and promotions.

    Back to top

    Implementing the Design in Your Website

    After you have designed the look and feel of your search engine, you can implement it in your webpage by doing the following:

    1. Click Save in the Look and feel tab.
    2. Click Get Code.
    3. Copy the code snippet generated in the Get code tab.

      If you have selected the two-column layout, copy two pieces of code snippets: one for the search box, and the other for results.
      If you have selected two-page layout, type the URL of the webpage that will show the results for your search engine. Type the query parameter name embedded in the url, which is parsed by search results page. Finally, copy the two pieces of code snippets.
      The code snippet for results-only layout is for the case where search results are shown in a new page. Type the query parameter name embedded in the url, which is parsed by the search results page. Finally, copy the the search results code snippet. Alternatively, you can display the search results in the same page as your own search box, which calls the customSearchControl.execute() function, as in this demo.

    4. Insert the code in every page where you want a Custom Search box. You can paste the code anywhere within the <body></body> tag of your webpage.

      Note: For the most cross-browser compatibility, it is recommended that your HTML pages use a supported doctype such as <!DOCTYPE html>.

      If you are using hover effects for your Search element, your HTML page must use a supported doctype such as <!DOCTYPE html>.
      If you have selected the two-column layout, insert the code for the search box in one column and the code for the results in another column.
      If you have selected the two-page layout, insert the code for the search box in the webpage where you want the search box to appear, and the code for the results in the webpage where you want the search results to appear.
      If you have selected the results-only layout, insert the code snippet in the webpage where you want the search results to appear.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.