chrome.sidePanel
- Description
Use the
chrome.sidePanelAPI to host content in the browser's side panel alongside the main content of a webpage. - Permissions
sidePanel - AvailabilityChrome 114+ MV3+
The Side Panel API is currently available in Chrome Beta 114.
Overview
Chrome features a built-in side panel that enables users to view more information alongside the main content of a webpage. The Side Panel API allows extensions to display their own UI in the side panel, enabling persistent experiences that complement the user's browsing journey.
Some features include:
- The side panel remains open when navigating between tabs (if set to do so).
- It can be available only on specific websites.
- As an extension page, side panels have access to all Chrome APIs.
- Within Chrome's settings, users can specify which side the panel should be displayed on.
Manifest
To use the Side Panel API, add the "sidePanel" permission in the extension manifest file:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}Use cases
The following sections demonstrate some common use cases for the Side Panel API. See Extension samples for complete extension examples.
Display the same side panel on every site
The side panel can be set initially from the "default_path" property in the "side_panel" key of the manifest to display the same side panel on every site. This should point to a relative path within the extension directory.
manifest.json:
{
"name": "My side panel extension",
...
"side_panel": {
"default_path": "sidepanel.html"
}
...
}sidepanel.html:
<!DOCTYPE html>
<html>
<head>
<title>My Sidepanel</title>
</head>
<body>
<h1>All sites sidepanel extension</h1>
<p>This side panel is enabled on all sites</p>
</body>
</html>Enable a side panel on a specific site
An extension can use sidepanel.setOptions() to enable a side panel on a specific tab. This example uses chrome.tabs.onUpdated() to listen for any updates made to the tab. It checks if the URL is www.google.com and enables the side panel. Otherwise, it disables it.
service-worker.js:
const GOOGLE_ORIGIN = 'https://www.google.com';
chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
if (!tab.url) return;
const url = new URL(tab.url);
// Enables the side panel on google.com
if (url.origin === GOOGLE_ORIGIN) {
await chrome.sidePanel.setOptions({
tabId,
path: 'sidepanel.html',
enabled: true
});
} else {
// Disables the side panel on all other sites
await chrome.sidePanel.setOptions({
tabId,
enabled: false
});
}
});When a user temporarily switches to a tab where the side panel is not enabled, the side panel will be hidden. It will automatically show again when the user switches to a tab where it was previously open.
When the user navigates to a site where the side panel is not enabled, the side panel will close and the extension will not show in the side panel drop-down menu.
For a complete example, see the Tab-specific side panel sample.
Enable the action icon to open the side panel
Developers can allow users to open the side panel when they click on the action toolbar icon with sidePanel.setPanelBehavior(). First, declare the "action" key in the manifest:
manifest.json:
{
"name": "My side panel extension",
...
"action": {
"default_title": "Click to open panel"
},
...
}Now, let's add this functionality to the previous example:
service-worker.js:
const GOOGLE_ORIGIN = 'https://www.google.com';
// Allows users to open the side panel by clicking on the action toolbar icon
chrome.sidePanel
.setPanelBehavior({ openPanelOnActionClick: true })
.catch((error) => console.error(error));
...With openPanelOnActionClick() enabled, you can also open the side panel using a keyboard shortcut by specifying an action command in the manifest as featured in the Tab-specific side panel sample.
Switch to a different panel
Extensions can use sidepanel.getOptions() to retrieve the current side panel. The following example sets a welcome side panel on runtime.onInstalled(). Then when the user navigates to a different tab, it replaces it with the main side panel.
service-worker.js:
const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';
chrome.runtime.onInstalled.addListener(() => {
chrome.sidePanel.setOptions({ path: welcomePage });
});
chrome.tabs.onActivated.addListener(async ({ tabId }) => {
const { path } = await chrome.sidePanel.getOptions({ tabId });
if (path === welcomePage) {
chrome.sidePanel.setOptions({ path: mainPage });
}
});See the Multiple side panels for a complete sample.
Side panel user experience
Users will see Chrome's built-in side panels first. Each side panel displays the extension's icon in the side panel menu. If no icons are included, it will show a placeholder icon with the first letter of the extension's name.
Opening the side panel
- Navigating to the side panel menu
- Users can find available side panels on the side panel menu. Then, they can choose an extension from the drop-down menu.
- Using the action toolbar icon
- Users can open the side panel by clicking on the action icon if it's enabled.
- Using a keyboard shortcut
- Users can open the side panel by pressing a keyboard shortcut if the action command and the action icon are enabled.
Extension samples
For more Side Panel API extensions demos, explore any of the following extensions:
Summary
- Types
- Methods
Types
GetPanelOptions
Properties
- tabId
number optional
If specified, the side panel options for the given tab will be returned. Otherwise, returns the default side panel options (used for any tab that doesn't have specific settings).
PanelBehavior
Properties
- openPanelOnActionClick
boolean optional
Whether clicking the extension's icon will toggle showing the extension's entry in the side panel. Defaults to false.
PanelOptions
Properties
- enabled
boolean optional
Whether the side panel should be enabled. This is optional. The default value is true.
- path
string optional
The path to the side panel HTML file to use. This must be a local resource within the extension package.
- tabId
number optional
If specified, the side panel options will only apply to the tab with this id. If omitted, these options set the default behavior (used for any tab that doesn't have specific settings). Note: if the same path is set for this tabId and the default tabId, then the panel for this tabId will be a different instance than the panel for the default tabId.
SidePanel
Properties
- default_path
string
Developer specified path for side panel display.
Methods
getOptions
chrome.sidePanel.getOptions(
options:
GetPanelOptions,
callback?:
function,
)
Returns the active panel configuration.
Parameters
- options
Specifies the context to return the configuration for.
- callback
function optional
The
callbackparameter looks like:(options: PanelOptions) => void- options
Returns
Promise<PanelOptions>
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getPanelBehavior
chrome.sidePanel.getPanelBehavior(
callback?:
function,
)
Returns the extension's current side panel behavior.
Parameters
- callback
function optional
The
callbackparameter looks like:(behavior: PanelBehavior) => void- behavior
Returns
Promise<PanelBehavior>
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setOptions
chrome.sidePanel.setOptions(
options:
PanelOptions,
callback?:
function,
)
Configures the side panel.
Parameters
- options
The configuration options to apply to the panel.
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setPanelBehavior
chrome.sidePanel.setPanelBehavior(
behavior:
PanelBehavior,
callback?:
function,
)
Configures the extension's side panel behavior. This is an upsert operation.
Parameters
- behavior
The new behavior to be set.
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.