By using the chrome.sidePanel API you can render your own HTML in the chrome browser’s side panel alongside the loaded website.
Official Documentation: https://developer.chrome.com/docs/extensions/reference/api/sidePanel
Why Use it?
- You can set the side panel to persists between tabs, have settings for example readily available
- Different Side UIs can be defined for different website.
- Just like the extension pages (popup UI) side panels have access to tall the chrome API. For instance
chrome.storagechrome.tabsand many more
How to declare it in Manifest.json
Use the sidePanel keyword in permissions to use the chrome.sidePanel API function in code like so
{
...
"permissions": [
"sidePanel"
],
...
}
Use the side_panelkeyword outside permissions to define default settings for the side panel for instance.
{
...
"permissions": [ ],
"side_panel": {
"default_path": "index.html"
},
...
}
How to open side panel
chrome.sidePanel.open({ tabId : "the-tab-id" }, () => {
console.log("Side Panel Opened");
});
// or the async/await version
await chrome.sidePanel.open({ tabId : "the-tab-id" });
console.log("Side Panel Opened");
So for example if you wanted to open side panel when the user clicks the action icon on the toolbar
chrome.action.onClicked.addListener((tab) =>{
chrome.sidePanel.open({ tabId : tab.id }, () => {
console.log("Side Panel Opened");
});
});
How to dynamically set UI for Side Panel.
Two functions are used to set the side panel properties in chrome.sidePanel.setOptions and chrome.sidePanel.setPanelBehavior .
//Configures the side panel.
chrome.sidePanel.setOptions({
// Whether sidepanel is enabled or not. By default it's true.
enabled: true,
// html file path
path: "index.html",
// the tab in which the sidepanel should appear. If omitted extensions assummes default behaviour.
// tabId: "tab-id"
})
chrome.sidePanel.setPanelBehavior({
// Whether clicking the extension's icon will
// toggle showing the extension's entry
// in the side panel. Defaults to false.
openPanelOnActionClick: true,
});
Let say you want set the index.html path for the side panel at install time and when a tab is activated it changes the side panel UI to a different html file.
This code snippet was provided by the Google Chrome Extension Team: https://developer.chrome.com/docs/extensions/reference/api/sidePanel#use-cases
const welcomePage = 'sidepanels/index.html';
const mainPage = 'sidepanels/main-sp.html';
chrome.runtime.onInstalled.addListener(() => {
chrome.sidePanel.setOptions({ path: welcomePage });
chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});
chrome.tabs.onActivated.addListener(async ({ tabId }) => {
const { path } = await chrome.sidePanel.getOptions({ tabId });
if (path === welcomePage) {
chrome.sidePanel.setOptions({ path: mainPage });
}
});
You can also retrieve the side panel options and behavior using the chrome.sidePanel.getOptions and chrome.sidePanel.getPanelBehavior respectively.
chrome.sidePanel.getOptions((options)=>{
console.log(options.tabId);
})
chrome.sidePanel.getPanelBehavior((behavior)=>{
console.log(behavior);
})
Sample Projects
There are some great examples the Chrome Team provides on GitHub.
- Dictionary side panel.
- Global side panel.
- Multiple side panels.
- Open Side panel.
- Site-specific side panel.
We, on the other hand, are going to a simple chrome extension that opens up the side panel when the action icon is clicked. You can find the source code for this project here: https://github.com/BuildChromeExtensions/chromeSidePanel
For this project we’ll need just 3 files sidebar.html, manifest.json and background.js
sidebar.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
<style>
body {
width: 200px;
height: 300px;
display: flex;
justify-content: center;
background: purple;
color: white;
text-align: center;
}
</style>
</head>
<body>
<h2>Side Panel Extension</h2>
</body>
</html>
manifest.json
{
"name": "Side Panels",
"manifest_version": 3,
"version": "1.0.0.0",
"action": {
"default_title": "Click to open side panel"
},
"permissions": [
"sidePanel"
],
"side_panel": {
"default_path": "sidebar.html"
},
"background": {
"service_worker": "background.js"
}
}
background.js
// When Action Icon is clicked
chrome.action.onClicked.addListener((tab) => {
// Open Side Panel
chrome.sidePanel.open({ tabId: tab.id }, () => {
console.log("Side Panel Opened");
});
});
Leave a Reply