Developer's Guide

Important: iGoogle will be retired on November 1, 2013. We are no longer accepting new theme submissions.

The Themes API lets you create custom designs for iGoogle, giving tens of millions of users tools to further personalize their homepage. Themes are dynamic designs--they can change throughout the day to reveal a visual storyline, message, or anything else.

This document marks sections as New! or Updated! to help you identify content that has changed since the last version.

Updated! There are two versions of iGoogle user interface (UI): the original UI, and the new UI, which the user can opt-in. Over time, the new UI will be replacing the old UI. For the themes of the original UI, please refer to this guide.


  1. What is a theme?
  2. Creating and testing themes
  3. Creating a dynamic theme
  4. Localizing a theme
  5. Submitting a theme
  6. Updating a theme

What is a theme?

A theme is a custom design for the iGoogle page. You define a theme in a basic XML file that contains key-value pairs for iGoogle page attributes, such as background images. A theme can be as simple as a simple background image, or it can include multiple images and dynamic behavior.

A theme has one or more skins. A skin specifies a look and feel for the attributes you want to include in your theme, creating a single design for the iGoogle page. A theme with multiple skins is a dynamic theme, changing the iGoogle page's design depending on the time of day.

Each skin is represented in the theme XML file by a different ConfigMap (configuration map). A theme is essentially a collection of configuration maps.

Here is a simple example that illustrates the basic syntax of the theme XML file. Note that skins are defined within <ConfigMap> tags. A theme can define multiple skins, and each skin is defined within a <ConfigMap> section. A theme needs at least two <ConfigMap> sections: one for the theme metadata (containing <Meta> tags); another for the design attributes (containing <Attribute> tags) for at least one skin.

Here is a simple example that illustrates the basic syntax of a theme XML file.

<?xml version="1.0" encoding="UTF-8"?>
 <ConfigMap type="Skin">
   <Meta name="title">Android</Meta>
   <Meta name="description">&#160;</Meta>
   <Meta name="author">Google</Meta>
   <Meta name="author_email"></Meta>
   <Meta name="full_page_thumbnail.url">
 <ConfigMap type="Skin">
   <Attribute name="full_page.background_image.url">

See the reference for a complete list of the attributes and metadata fields.

Updated! Creating and testing themes

You can write a theme XML file using any text editor.

To test a theme, you must host the XML file and theme images on a public server. For example, you could host your theme XML and image files through Google Code, as described here.

Once your theme resources are hosted, you can test the theme by adding ?skin=<theme-url> at the end of the iGoogle URL. For example, you can test the simple example shown above on an international version of iGoogle as follows:

Note: if you are a new user, you have to click "See your page" in the setup box to test a theme.

Creating a dynamic theme

Remember, the background image can all change throughout the day based on time of day or day of week. Feel free to create as many designs as you like (note that changes during hours at night are not seen often, and having too many images may cause users to miss a few if they don’t visit often).

When you have a dynamic theme, you create different skins for different time periods or day-of-week. Every skin must be fully qualified--that is, you must define all attributes for every skin. You use the <Trait> tag to specify the period of time that applies to that particular skin.

A Time-of-day Example

<ConfigMap type="Skin">
<Trait name="TimeOfDay">12am-1am</Trait>
<ConfigMap type="Skin"> <Trait name="TimeOfDay">1am-2am</Trait> ...attributes... </ConfigMap> ...

Valid time ranges are from 12am - 12am. If the end time is before the start time, it will cause a submit-time error. For example, suppose that you want to specify a time span from 11pm-5am. This time span would be invalid. To make it work, you would have to split it up into two Traits, one with TimeOfDay from 11pm-12am, and another with TimeOfDay from 12am-5am. You can also refer to the Ocean theme as an example.

New! A Day-of-week Example

<ConfigMap type="Skin">
<Trait name="DayOfWeek">sun</Trait>
<Trait name="DayOfWeek">mon</Trait>

Valid DayOfWeek values are: sun, mon, tue, wed, thu, fri, sat You can also refer to the Planets theme as an example.

Localizing a theme

You can help users around the world to find your theme by including localized metadata fields for particular languages and countries. You can localize the following fields:

  • title. Title displayed in the Themes directory.
  • description. Description of the theme and what it does.
  • thumbnail. Thumbnail that appears in the Themes directory to give users a preview of a theme.
  • screenshot. Screenshot that appears in the Themes directory on the page about your theme.

To localize these fields, include an additional <ConfigMap> in your theme XML file for each language and country you want to support. If a language or country is not included in the theme, the theme's directory defaults to the first <ConfigMap> that does not have a language or country specified. For example:

  <!-- These values are the defaults for all countries -->
  <ConfigMap type="Skin">
    <Meta name="title">Simple Theme</Meta>
    <Meta name="description">Simple theme example.</Meta>
    <Meta name="author">Rowan</Meta>
    <Meta name="author_email"></Meta>
    <Meta name="thumbnail"></Meta>
    <Meta name="screenshot"></Meta>
  <!-- Localized fields, which will replace the defaults for language ja, and country jp -->
  <ConfigMap type="Skin">
    <Trait name="Language">ja</Trait>
    <Trait name="Country">jp</Trait>
    <Meta name="title">単純なテーマ</Meta>
    <Meta name="description">単純なテーマの例</Meta>
    <Meta name="thumbnail"></Meta>
    <Meta name="screenshot"></Meta>

You are not required to specify both a language and a country. You can just specify one or the other. For example, you could create a <ConfigMap> for all French speakers, or you could create a <ConfigMap> that only applies to French speakers in Canada. It depends on how specifically you want to target a particular audience.

The valid values for Language are ISO639-1 two-digit language codes, and for Country they are ISO 3166-1 alpha-2 codes. For a list of the languages and countries supported by iGoogle, see iGoogle Supported Languages and Countries.

Submitting a theme

You can use the Themes API to create simple designs for yourself and your friends. However, unless a theme is in the iGoogle Themes directory, you can only apply it in "test mode" through the URL, as described in Creating and testing themes. To share your theme with a wider audience and make it possible for users to persistently apply your theme to iGoogle, you must submit it to the iGoogle Themes directory. For a theme to be included in the iGoogle Themes directory, it must be a compelling, polished, tested design that conforms to the guidelines given in the program policy. You must also include all of the metadata fields and ensure that all images used in the theme are publicly accessible.

Once your theme is ready, you can submit it here. When Google accepts your theme and includes it in the Themes directory, your images are copied over and hosted by Google, so you don't need to worry about traffic to your host.

If you have problems submitting your theme, make sure that all of the syntax is correct and that there are no blank lines in your themes XML file. If you have any questions or feedback, please visit the Themes API group.

Updating a theme

If you want to make changes to a theme you've already submitted, just submit the theme again using the same url and it will be updated in about 1-2 weeks.

Back to top