README.md
1New Tab Page (Desktop) 2====================== 3 4On Desktop (ChromeOS, Windows, Mac, and Linux), there are multiple 5variants of the **New Tab Page** (**NTP**). The variant is selected 6according to the user’s **Default Search Engine** (**DSE**). All 7variants are implemented as HTML/CSS/JS, but differ in where they are 8hosted. 9 10* **Google**: The **[Local NTP][local-ntp]**, with Google branding. 11 12* **Bing**, **Yandex**: a **[Third-Party NTP][third-party-ntp]**, 13 where the NTP is hosted on third-party servers but Chrome provides 14 some of the content via <iframe> elements. 15 16* **Other**: the **Local NTP** with no branding. 17 18As of 2017-12-05, Bing and Yandex have implemented third-party NTPs. The 19full list is in [`prepopulated_engines.json`][engines], under the key 20`"new_tab_url"`. 21 22Non-Google variants show up to 8 **NTP Tiles**. Each NTP tile represents a site 23that Chrome believes the user is likely to want to visit. On Desktop, NTP tiles 24have a title, a large icon, and an “X” button so that the user can remove tiles 25that they don’t want. 26 27Google variants show up to 10 **NTP Tiles** (now called shortcuts) and give 28users the ability to customize them. This includes adding new shortcuts using 29the "Add shortcut" button, deleting/editing shortcuts from the three-dot "Edit 30shortcut" menu (replaces the "X" button), and reordering via click-and-drag. 31 32[local-ntp]: #local-ntp 33[third-party-ntp]: #third_party-ntp 34[engines]: https://chromium.googlesource.com/chromium/src/+/master/components/search_engines/prepopulated_engines.json 35 36Variants 37-------- 38 39### Local NTP 40 41#### Google branding 42 43##### One Google Bar 44 45The **One Google Bar** (**OGB**) is at the top of the NTP. The NTP 46fetches the OGB from Google servers each time it loads. 47 48##### Google Logo 49 50The **Google Logo** is below the OGB. By default, it is the regular 51Google logo. It can also be a **Doodle**, if a Google Doodle is running 52for a particular combination of (today’s date, user’s country, user’s 53birthday). 54 55###### No Doodle 56 57On a day when there is no Doodle (in the user’s current country), the 58NTP shows the Google logo. It comes in two variants: 59 60* Colorful, if the user is using the default theme, or on any other 61 theme with a solid black (L=0%), white (L=100%), or gray (S=0%) 62 background color. 63* White, if the user’s theme has a background image, or if the 64 background is a solid color, but not black, white, or gray. 65 66Also, even on days when there is a Doodle, if the user’s theme’s 67background is not solid white, new NTPs show the Google logo by default. 68In this case, an animated spinner advertises the Doodle. If the user 69clicks on the spinner, then the NTP resets to the default theme and 70shows the Doodle. 71 72###### Static Doodles 73 74A **Static Doodle** shows as a single static image. When clicked, it 75triggers a navigation to the Doodle’s target URL. 76 77###### Animated Doodles 78 79An **Animated Doodle** initially shows a static **Call-to-Action** 80(**CTA**) image, usually with a “play” icon. When clicked, it swaps out 81the CTA image for an animated image. When clicked a second time, it 82triggers a navigation to the Doodle’s target URL. 83 84###### Interactive Doodles 85 86An **Interactive Doodle** is embedded into the NTP as an `<iframe>`. 87The framed content usually contains a CTA image, but this is opaque to 88the containing NTP. 89 90The embedded Doodle can ask the containing NTP to resize the `<iframe>` 91tag to enlarge the space available for the Doodle. To do this, it sends 92a `postMessage()` call to `window.parent`. The event data supports these 93parameters: 94 95* `cmd` (required string): must be `"resizeDoodle"`. 96* `width` (required string): a CSS width (with units). Because the 97 Doodle cannot know the size of the outer page, values based on 98 `"100%"` (e.g. `"100%"` or `"calc(100% - 50px)"`) are recommended. 99* `height` (required string): a CSS height (with units). Must not be a 100 percentage, but otherwise any units are OK. 101* `duration` (optional string): a CSS duration, such as `"130ms"` or 102 `"1s"`. If `null` or absent, `"0s"` (no transition) is assumed. 103 104For example: 105 106 // Reset to initial width and height. 107 window.parent.postMessage({cmd: "resizeDoodle"}); 108 109 // Transition smoothly to full-width, 350px tall. 110 window.parent.postMessage({ 111 cmd: "resizeDoodle", 112 width: "100%", 113 height: "350px", 114 duration: "1s", 115 }); 116 117##### Fakebox 118 119The **Fakebox** looks like a search bar, so that the NTP mimics the 120appearance of the Google homepage. It’s not actually a real search bar, 121and if the user interacts with it, the NTP moves keyboard focus and any 122text to the Omnibox and hides the Fakebox. 123 124##### Search Suggestions 125 126Above the NTP tiles there is space for search suggestions. Search suggestions 127are typically 3-4 queries recommended to logged-in users based on their previous 128search history. 129 130Search suggestions are fetched from Google servers on NTP load and cached to be 131displayed on the following NTP load. 132 133##### Middle-slot Promos 134 135Below the NTP tiles, there is space for a **Middle-slot Promo**. A promo is 136typically a short string, typically used for disasters (e.g. “Affected 137by the Boston Molassacre? Find a relief center near you.”) or an 138advertisement (e.g. “Try the all-new new Chromebook, with included 139toaster oven.”). 140 141Middle-slot promos are fetched from Google servers on NTP load. 142 143#### Non-Google Local NTP 144 145A non-Google local NTP shows only NTP tiles, with no branding. The tiles 146are centered within the page. 147 148### Third-Party NTP 149 150TODO(sfiera) 151