1<div id="pageData-name" class="pageData">Override Pages</div>
2<div id="pageData-showTOC" class="pageData">true</div>
3
4<style>
5#pics {
6  margin:2em 1em 1.5em;
7}
8
9#pics td {
10  text-align:center;
11  width:50%!important;
12  border:none;
13  padding:0 1em;
14  font-size:90%;
15}
16
17#pics img {
18  width:188;
19  height:246;
20  border:none;
21}
22</style>
23
24<p>
25Override pages are a way to substitute an HTML file from your extension
26for a page that Google Chrome normally provides.
27In addition to HTML,
28an override page usually has CSS and JavaScript code.
29</p>
30
31<p>
32An extension can replace any one of the following pages:
33<ul>
34  <li> <b>Bookmark Manager:</b>
35  The page that appears when the user chooses
36  the Bookmark Manager menu item
37  from the wrench menu or, on Mac,
38  the Bookmark Manager item from the Bookmarks menu.
39  You can also get to this page by entering the URL
40  <b>chrome://bookmarks</b>.
41  </li>
42
43  <li> <b>History:</b>
44  The page that appears when the user
45  chooses the History menu item
46  from the Tools (wrench) menu or, on Mac,
47  the Show Full History item from the History menu.
48  You can also get to this page by entering the URL
49  <b>chrome://history</b>.
50  </li>
51
52  <li> <b>New Tab:</b>
53  The page that appears when the user creates a new tab or window.
54  You can also get to this page by entering the URL
55  <b>chrome://newtab</b>.
56  </li>
57</ul>
58</p>
59
60<p class="note">
61<b>Note:</b>
62A single extension can override
63<b>only one page</b>.
64For example, an extension can't override both
65the Bookmark Manager and History pages.
66</p>
67
68<p>
69Incognito windows are treated specially.
70New Tab pages cannot be overridden in incognito windows.
71Other override pages work in incognito windows
72as long as the
73<a href="manifest.html#incognito">incognito</a>
74manifest property is set to "spanning"
75(which is the default value for extensions
76but not for packaged apps).
77See <a href="overview.html#incognito">Saving data and incognito mode</a>
78in the Overview for more details on how you should treat
79incognito windows.
80</p>
81
82<p>
83The following screenshots show the default New Tab page
84next to a custom New Tab page.
85</p>
86
87<table id="pics">
88  <tr>
89    <td> <b>The default New Tab page</b> </td>
90    <td> <b>An alternative New Tab page</b> </td>
91  </tr>
92  <tr>
93    <td>
94      <img src="images/ntp-default.png"
95        alt="default New Tab page"
96        width="200" height="173">
97    </td>
98    <td>
99      <img src="images/ntp-blank.png"
100        alt="a blank New Tab page"
101        width="200" height="173">
102    </td>
103  </tr>
104</table>
105
106<h2 id="manifest">Manifest</h2>
107
108<p>
109Register an override page in the
110<a href="manifest.html">extension manifest</a> like this:
111</p>
112
113<pre>{
114  "name": "My extension",
115  ...
116
117<b>  "chrome_url_overrides" : {
118    "<em>pageToOverride</em>": "<em>myPage.html</em>"
119  }</b>,
120  ...
121}</pre>
122
123<p>
124For <code><em>pageToOverride</em></code>, substitute one of the following:
125</p>
126
127<ul>
128  <li> <code>bookmarks</code>
129  <li> <code>history</code>
130  <li> <code>newtab</code>
131</ul>
132
133
134<h2 id="tips">Tips</h2>
135
136<p>
137For an effective override page, follow these guidelines:
138</p>
139
140<ul>
141  <li>
142    <p>
143    <b>Make your page quick and small.</b> <br />
144    Users expect built-in browser pages to open instantly.
145    Avoid doing things that might take a long time.
146    For example, avoid synchronous fetches of network or database resources.
147    </p>
148  </li>
149  <li>
150    <p>
151    <b>Include a title in your page.</b> <br />
152    Otherwise people might see the URL of the page,
153    which could be confusing.
154    Here's an example of specifying the title:
155    <code>&lt;title>New&nbsp;Tab&lt;/title></code>
156    </p>
157  </li>
158  <li>
159    <p>
160    <b>Don't rely on the page having the keyboard focus.</b> <br />
161    The address bar always gets the focus first
162    when the user creates a new tab.
163    </p>
164  </li>
165  <li>
166    <p>
167    <b>Don't try to emulate the default New Tab page.</b> <br />
168    The APIs necessary to create
169    a slightly modified version of the default New Tab page &mdash;
170    with top pages,
171    recently closed pages,
172    tips,
173    a theme background image,
174    and so on &mdash;
175    don't exist yet.
176    Until they do,
177    you're better off trying to make something completely different.
178    </p>
179  </li>
180</ul>
181
182<h2 id="examples"> Examples </h2>
183
184<p>
185See the
186<a href="samples.html#chrome_url_overrides">override samples</a>.
187</p>
188