Skip to content
This repository was archived by the owner on Mar 23, 2026. It is now read-only.

Commit feec4b9

Browse files
jpmedleyjpmedley
authored
Consolidate action material (GoogleChrome#7398)
* Consolidate action material If the action material is on the same page is should be in the same place. * Move another action-related content block. * Move additional action instructions. * Move the Tooltip section. * Move popup information to action section.
1 parent 667f301 commit feec4b9

File tree

1 file changed

+107
-107
lines changed
  • site/en/docs/extensions/mv3/user_interface

1 file changed

+107
-107
lines changed

‎site/en/docs/extensions/mv3/user_interface/index.md‎

Lines changed: 107 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,18 @@ description: User interface and design guidelines for Chrome Extensions.
99

1010
Like Chrome's user interface, an extension user interface should be purposeful and minimal. Extensions
1111
should allow users to customize or enhance the user's browsing experience without distracting
12-
from it.
12+
from it.
1313

1414
This guide explores required and optional user interface features. Use it to understand how and when
1515
to implement different user interface elements within an extension.
1616

1717
## The extension action {: #action }
1818

1919
The [Action API][api-action] controls the extension's action (toolbar icon). It can either open a
20-
[popup][section-popup] or trigger some functionality when it's [clicked][section-onclick].
20+
[popup][section-popup] or trigger some functionality when it's [clicked][section-onclick].
2121

2222
Users can trigger an extension's action by expanding the extension menu and selecting the desired
23-
extension.
23+
extension.
2424

2525
To make it easier to access an extension, the user may choose to pin the extension's action to the
2626
toolbar. Once pinned, the extension's action will appear to the left of the extension menu. Users
@@ -29,7 +29,7 @@ order.
2929

3030
{% Columns %}
3131

32-
{% Column %}
32+
{% Column %}
3333

3434
<figure>
3535
{% Img src="image/BhuKGJaIeLNPW9ehns59NfwqKxF2/iouvm1a3lsQWGyg6fSMS.png", alt="Unpinned extension",
@@ -39,7 +39,7 @@ width="400", height="374", class="screenshot" %}
3939

4040
{% endColumn %}
4141

42-
{% Column %}
42+
{% Column %}
4343

4444
<figure>
4545
{% Img src="image/BhuKGJaIeLNPW9ehns59NfwqKxF2/KS09fVoCj3YWuIoH5EFn.png", alt="Pinned extension",
@@ -81,89 +81,31 @@ When an extension is disabled, the icon is grayed out. If the user clicks the di
8181
the extension's context menu will appear.
8282

8383
<figure>
84-
{% Img src="image/BhuKGJaIeLNPW9ehns59NfwqKxF2/hlYsQJPFsF7WBAjJZ6DS.png",
85-
alt="Clicked Disabled extension", width="252", height="180", class="screenshot" %}
84+
{% Img src="image/BhuKGJaIeLNPW9ehns59NfwqKxF2/hlYsQJPFsF7WBAjJZ6DS.png",
85+
alt="Clicked Disabled extension", width="252", height="180", class="screenshot" %}
8686

8787
<figcaption>
8888
Disabled extension.
8989
</figcaption>
9090
</figure>
9191

92-
## Provide the extension icons
93-
94-
An extension requires at least one icon to represent it. Provide icons in PNG format for the best
95-
visual results, although any raster format supported by Chrome is accepted. This includes BMP,
96-
GIF, ICO, and JPEG.
97-
98-
{% Aside 'caution' %}
99-
100-
SVG files are not supported for any icons declared in the manifest.
101-
102-
{% endAside %}
103-
104-
Ensure your icon follows the [extension icon best practices][docs-icon-guidelines].
105-
106-
### Designate action icons {: #icons }
107-
108-
Icons specific to the toolbar are registered in the `"default_icon"` field under
109-
[`"action"`][api-action] in the manifest. Including multiple sizes is encouraged to scale for the
110-
16-dip space. At minimum, 16x16 and 32x32 sizes are recommended.
111-
112-
{% Label %}manifest.json:{% endLabel %}
113-
114-
```json
115-
{
116-
"name": "My Awesome Extension",
117-
...
118-
"action": {
119-
"default_icon": {
120-
"16": "extension_toolbar_icon16.png",
121-
"32": "extension_toolbar_icon32.png"
122-
}
123-
}
124-
...
125-
}
126-
```
127-
128-
All icons should be square or they may be distorted. If no icons are supplied, Chrome will add a
129-
generic one to the toolbar with the first letter of the extension name.
130-
131-
### Create and register additional icons {: #icon_size }
132-
133-
Include additional icons in the following sizes for uses outside of the toolbar.
92+
### Respond to the action {: #click}
13493

135-
| Icon Size | Icon Use |
136-
|-----------|--------------------------------------------------------|
137-
| 16x16 | Favicon on the extension's pages and context menu icon.|
138-
| 32x32 | Windows computers often require this size. |
139-
| 48x48 | Displays on the extension management page. |
140-
| 128x128 | Displays on installation and in the Chrome Web Store. |
141-
142-
143-
Register icons in the manifest under the `"icons"` field.
94+
It's possible to register an [`OnClicked` handler][action-onclicked] for when the user clicks the action
95+
item. However, this won't fire if the action has a popup (default or otherwise).
14496

145-
{% Label %}manifest.json:{% endLabel %}
97+
{% Label %}service-worker.js:{% endLabel %}
14698

147-
```json
148-
{
149-
"name": "My Awesome Extension",
150-
...
151-
"icons": {
152-
"16": "extension_icon16.png",
153-
"32": "extension_icon32.png",
154-
"48": "extension_icon48.png",
155-
"128": "extension_icon128.png"
156-
}
157-
...
158-
}
99+
```js
100+
chrome.action.onClicked.addListener((tab) => {
101+
chrome.action.setTitle({tabId: tab.id, title: `You are on tab: ${tab.id}`});
102+
});
159103
```
160104

161-
## Additional user interface features {: #additional_features }
162-
163105
### Action badge {: #badge }
164106

165107
Badges display a colored banner on top of the action icon. They can only be used when the `"action"`
166-
is declared in the manifest.
108+
is declared in the manifest.
167109

168110
Use badges to indicate the state of the extension. The [Drink Water][sample-drink] sample extension
169111
displays a badge with "ON" to show the user they have successfully set an alarm and displays nothing when
@@ -175,7 +117,7 @@ the extension is idle. Badges can contain up to 4 characters.
175117

176118
<figure>
177119
{% Img src="image/BrQidfK9jaQyIHwdw91aVpkPiib2/nXwAHSWLBEgT8099ITT0.png", alt="Badge On",
178-
height="72", width="72" %}
120+
height="72", width="72" %}
179121
<figcaption>
180122
An action icon with a badge.
181123
</figcaption>
@@ -185,11 +127,11 @@ the extension is idle. Badges can contain up to 4 characters.
185127

186128
{% endColumn %}
187129

188-
{% Column %}
130+
{% Column %}
189131

190132
<figure>
191133
{% Img src="image/BrQidfK9jaQyIHwdw91aVpkPiib2/pNz8UgfTBMmcf7fE9wja.png", alt="Badge Off",
192-
height="72", width="72" %}
134+
height="72", width="72" %}
193135
<figcaption>
194136
An action icon without a badge.
195137
</figcaption>
@@ -212,6 +154,29 @@ chrome.action.setBadgeText({text: 'ON'});
212154
chrome.action.setBadgeBackgroundColor({color: '#4688F1'});
213155
```
214156

157+
### Designate action icons {: #icons }
158+
159+
Icons specific to the toolbar are registered in the `"default_icon"` field under
160+
[`"action"`][api-action] in the manifest. Including multiple sizes is encouraged to scale for the
161+
16-dip space. At minimum, 16x16 and 32x32 sizes are recommended.
162+
163+
{% Label %}manifest.json:{% endLabel %}
164+
165+
```json
166+
{
167+
"name": "My Awesome Extension",
168+
...
169+
"action": {
170+
"default_icon": {
171+
"16": "extension_toolbar_icon16.png",
172+
"32": "extension_toolbar_icon32.png"
173+
}
174+
}
175+
...
176+
}
177+
```
178+
179+
215180
### Popup {: #popup }
216181

217182
A popup is an HTML file that is displayed in a special window when the user clicks the action icon.
@@ -222,7 +187,7 @@ The [Drink Water Event][sample-drink] example popup displays available timer opt
222187
alarm by clicking one of the provided buttons.
223188

224189
<figure>
225-
{% Img src="image/BrQidfK9jaQyIHwdw91aVpkPiib2/JVduBMXnyUorfNjFZmue.png", alt="The Drink Water popup", height="361", width="213", class="screenshot" %}
190+
{% Img src="image/BrQidfK9jaQyIHwdw91aVpkPiib2/JVduBMXnyUorfNjFZmue.png", alt="The Drink Water popup", height="361", width="213", class="screenshot" %}
226191
<figcaption>
227192
The Drink Water popup.
228193
</figcaption>
@@ -275,7 +240,68 @@ chrome.storage.local.get('signed_in', (data) => {
275240
});
276241
```
277242

278-
### Side panel {: #side-panel }
243+
### Tooltip {: #tooltip }
244+
245+
Use a tooltip to give short descriptions or instructions to users when they hover over the action
246+
icon. By default, the tootip displays the name of the extension.
247+
248+
<figure>
249+
{% Img src="image/BrQidfK9jaQyIHwdw91aVpkPiib2/Go8aQg0vd0f2hkOFElLK.png", alt="An
250+
example tooltip", height="157", width="419", class="screenshot" %}
251+
<figcaption>
252+
An example tooltip.
253+
</figcaption>
254+
</figure>
255+
256+
## Provide the extension icons
257+
258+
An extension requires at least one icon to represent it. Provide icons in PNG format for the best
259+
visual results, although any raster format supported by Chrome is accepted. This includes BMP,
260+
GIF, ICO, and JPEG.
261+
262+
{% Aside 'caution' %}
263+
264+
SVG files are not supported for any icons declared in the manifest.
265+
266+
{% endAside %}
267+
268+
Ensure your icon follows the [extension icon best practices][docs-icon-guidelines].
269+
270+
271+
All icons should be square or they may be distorted. If no icons are supplied, Chrome will add a
272+
generic one to the toolbar with the first letter of the extension name.
273+
274+
Include additional icons in the following sizes for uses outside of the toolbar. {: #icon_size }
275+
276+
| Icon Size | Icon Use |
277+
|-----------|--------------------------------------------------------|
278+
| 16x16 | Favicon on the extension's pages and context menu icon.|
279+
| 32x32 | Windows computers often require this size. |
280+
| 48x48 | Displays on the extension management page. |
281+
| 128x128 | Displays on installation and in the Chrome Web Store. |
282+
283+
284+
Register icons in the manifest under the `"icons"` field.
285+
286+
{% Label %}manifest.json:{% endLabel %}
287+
288+
```json
289+
{
290+
"name": "My Awesome Extension",
291+
...
292+
"icons": {
293+
"16": "extension_icon16.png",
294+
"32": "extension_icon32.png",
295+
"48": "extension_icon48.png",
296+
"128": "extension_icon128.png"
297+
}
298+
...
299+
}
300+
```
301+
302+
## Additional user interface features {: #additional_features }
303+
304+
### Side panel {: #side-panel }
279305

280306
An extension side panel is an HTML file that provides additional functionality alongside the main content of a web page. The [Dictionary side panel][sample-dictionary-sidepanel] example allows users to right-click on a word and see the definition in the side panel.
281307

@@ -295,19 +321,6 @@ An extension side panel is an HTML file that provides additional functionality a
295321

296322
For more samples and use cases, see the [Side Panel API][api-sidepanel] reference page.
297323

298-
### Tooltip {: #tooltip }
299-
300-
Use a tooltip to give short descriptions or instructions to users when they hover over the action
301-
icon. By default, the tootip displays the name of the extension.
302-
303-
<figure>
304-
{% Img src="image/BrQidfK9jaQyIHwdw91aVpkPiib2/Go8aQg0vd0f2hkOFElLK.png", alt="An
305-
example tooltip", height="157", width="419", class="screenshot" %}
306-
<figcaption>
307-
An example tooltip.
308-
</figcaption>
309-
</figure>
310-
311324
Tooltips are registered in the `"default_title"` field under the `"action"` key in the manifest.
312325

313326
{% Label %}manifest.json:{% endLabel %}
@@ -325,19 +338,6 @@ Tooltips are registered in the `"default_title"` field under the `"action"` key
325338

326339
Tooltips can also be set or updated by calling [`action.setTitle()`][action-settitle].
327340

328-
### Click Event {: #click}
329-
330-
It's possible to register an [`OnClicked` handler][action-onclicked] for when the user clicks the action
331-
item. However, this won't fire if the action has a popup (default or otherwise).
332-
333-
{% Label %}service-worker.js:{% endLabel %}
334-
335-
```js
336-
chrome.action.onClicked.addListener((tab) => {
337-
chrome.action.setTitle({tabId: tab.id, title: `You are on tab: ${tab.id}`});
338-
});
339-
```
340-
341341
### Omnibox {: #omnibox }
342342

343343
Users can invoke extension functionality through the [Omnibox API][api-omnibox]. Include the `"omnibox"`
@@ -575,7 +575,7 @@ permission in the manifest.
575575
{% Label %}manifest.json:{% endLabel %}
576576

577577
```json/5
578-
{
578+
{
579579
"name": "Drink Water Event Popup",
580580
...
581581
"permissions": [
@@ -608,7 +608,7 @@ function showStayHydratedNotification() {
608608
```
609609

610610
<figure>
611-
{% Img src="image/BhuKGJaIeLNPW9ehns59NfwqKxF2/e5S112AtwfnA5o64JrGg.png",
611+
{% Img src="image/BhuKGJaIeLNPW9ehns59NfwqKxF2/e5S112AtwfnA5o64JrGg.png",
612612
alt="Mac OS notification", width="500", height="150", class="screenshot" %}
613613
<figcaption>
614614
Notification on macOS.

0 commit comments

Comments
 (0)