My favorites | English | Sign in

Google Custom Search API

Designing the Look and Feel

The previous pages discussed various ways to customize the coverage of your search engine and the ranking of its search results. This page discusses how you can customize the look and feel of your search box and search results using the control panel.

Contents

This page includes the following sections:

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. In the control panel, most look-and-feel settings are in—surprise!—the Look and feel tab of the control panel. After you are satisfied with settings, remember to click Save before you move to another tab.

If you do not want ads in your search results page, upgrade to the Site Search edition. If you want more flexibility in how you display and manipulate search results, you can use the Google AJAX Search API. You must be familiar with CSS and JavaScript to take full advantage of the API.

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

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 hosting option.
  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. Feel free to experiment with the values while you preview the changes.

  4. Click Save
  5. Implement the design in your website.

Back to top

Hosting the Results

Determine whether you want your search results to appear in a page hosted by Google or in your webpages. The hosting option you select also determines the level of customization you can make. The search element option allows the greatest level of customization, while the Google-hosted page option is the simplest, but provides the least level of customization.

You can choose the following hosting options in the Look and feel tab of the control panel:

  • Search element - Lets you display your search results in the same webpage as the search box. A search element is an object that you can embed in your webpage. It shows the search box and search results together in the same webpage that the reader is viewing. When your users do searches, they are not taken to another webpage, unless they click links in the results section. If your users remain in the same page, they can close the results section and resume reading the webpage. This option, when paired with a compact layout, works well on mobile devices.

    You can also take advantage of the AJAX Search API to further customize the search UI. You can, for example, create a Web 2.0 look and feel.

    If you do not want to tinker with AJAX, the elements option can still provide you with more customization choices. For example, you can select among three layouts for your results page, or you can download the CSS and make changes to it.

  • iframe - Lets you host the results page in one of your webpages. You must use an iframe, which is an HTML structure that lets you embed an HTML page. When users search for queries, they are taken to that search results page.
  • Google-hosted page - Lets Google host the results. The simplest option, but does not have the flexibility of the other options. You just add the search box in your webpage, while the search results page is hosted by Google. See an example of a Google-hosted search engine.

Back to top

The Search Element Layout (Search Elements Only)

If you are hosting the results page using search elements, you have the option to customize how your search UI is laid out on the webpage. You can have the search box and results section displayed in the same column, or you can place the search box in one column, and the results section in another column.

Your options are:

  • Full-width - 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 - 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 mobile devices, so it works well on iPhone, Android devices, and Pre.

  • Two Column - The search box and the search results section can be placed 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.

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. Choose one of the Custom Search search box designs.
  2. Implement the search box in your webpages.

Custom Search has the following sets of search box designs that you can choose from:

Back to top

Customizing the Search Box for Search Elements (Search Elements Only)

If you selected search elements as your hosting option, 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 for the input field for search queries.
      • Search button: Border color - the color of the lines that border the search button. The thin line might not be apparent if the color of the border is similar to the color of the button.
      • Search button: Background color - the color of the search button.
    3. Click Save.
  • Change the font style for the search button:
    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 below the style tabs show the changes you made in the settings.

For instructions for customizing refinement tabs, see The Refinement Tabs section.

Back to top

Selecting the Search Box for the iframe and Google-Hosted Pages

If you selected either the iframe or Google-hosted option, you can select one of the standard search boxes by doing the following in the style tabs:

  1. Select the Search Controls tab.
  2. Select one of the search boxes. To see how these options might appear, see the following table.
Search box design Preview
Watermark Search box with the Custom Search watermark
Branding below the search box (white background) Search box that is narrow in a white background
Branding below the search box (gray background) Search box that is narrow in a gray background
Branding below the search box (black background) Search box that is narrow in a black background
Branding on the side of the search box (white background) Search box that is narrow in a white background
Branding on the side of the search box (white background) Search box that is narrow in a gray background
Branding on the side of the search box (white background) Search box that is wide in a black background

Back to top

Designing the Results

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

Note: The preview is for results that use search elements only. To learn more, see Previewing Your Search Engine.

The Background Color

To change the background color of your 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.

If you are using search elements, 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 Font Type (Search Elements Only)

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 - For elements only. The title when the user hovers the mouse over the link.
      • Active color -For elements only. 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.
    • Results (normal state) styling -For elements only. 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 -For elements only. The set of definitions control 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

    The Refinement Tabs (Search Elements Only)

    If you have created refinement labels in your search engine, the labels appear as tabs in the search element and as links in iframe and Google-hosted pages. If you are using search elements, 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 lines that border 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 button.
        • 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 lines that border the tab that is currently selected.
        • Background color - the color of the tab the tab that is currently selected
    3. Click Save.

    Back to top

    The 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 elements only. The title when the user hovers the mouse over the link.
        • Active color -For elements 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 elements only.
        • Border color - the border of the promotion result.
        • Background color - the background color of the promotion result.
    3. Click Save.

    The Logo (Google-Hosted Page 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 (presumably 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 3: Search box with an image

    To add or change a logo in your Google hosted-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 only 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 elements, 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

    The preview is for results that use search elements only. If you enter a query and click Search, you can preview the results, including the promotions.

    If you are using iframe or Google-hosted pages, you can use the preview pane as a starting point. It gives you a general idea of how your results page might look.

    To see how your changes are reflected in iframe and Google-hosted pages, do the following:

    1. In your browser, open a new tab or window.
    2. Click My Search Engines.
    3. Click the name of the search engine you want to preview.
    4. In the homepage of that search engine, enter a query to see the results page.
    5. Refresh this tab or window as you make changes in the Look and feel tab. Remember to click Save before you preview the results page.

    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 for search elements, copy two pieces of code snippets: one for the search box, and the other for results.
      If you have selected iframe results, type the URL of the webpage that will show the results for your search engine. Also specify where you want the ads to be placed. Finally, copy the two pieces of code snippets.

    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.

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

    Taking the Next Step

    Well, you are done reading about all the cool features and tools you can use on your custom search engine, so how about making some money from your brilliantly crafted work of genius? When you get your checks, remember to thank the person who slaved over the developer guide.

    < Back to Creating Special Results | Forward to Making Money >