Complete reference for all browser extension APIs and methods
Essential APIs for extension functionality
Use the chrome.runtime API to retrieve the background page, return details about the manifest, and listen for and respond to events in the extension lifecycle.
Send a message to event listeners within your extension or a different extension.
SYNTAX
chrome.runtime.sendMessage(
extensionId?: string,
message: any,
options?: object,
callback?: function
)PARAMETERS
extensionId
The ID of the extension to send the message to.
message
The message to send. This can be any JSON-serializable object.
callback
Function called when a response is received.
EXAMPLE
// Send message
chrome.runtime.sendMessage({greeting: "hello"}, function(response) {
console.log(response.farewell);
});
// Listen for message
chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
console.log(request.greeting);
sendResponse({farewell: "goodbye"});
});Converts a relative path within an extension to a fully-qualified URL.
SYNTAX
chrome.runtime.getURL(path: string)EXAMPLE
let url = chrome.runtime.getURL('images/icon.png');
console.log(url); // chrome-extension://[extension-id]/images/icon.pngFired when the extension is first installed, updated, or Chrome is updated.
chrome.runtime.onInstalled.addListener(function(details) {
console.log('Extension installed:', details.reason);
if(details.reason === "install"){
// First install
} else if(details.reason === "update"){
// Extension updated
}
});Fired when a message is sent from an extension process or content script.
chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
if (request.action === "getData") {
sendResponse({data: "Response data"});
}
return true; // Required for async response
});Use the chrome.storage API to store, retrieve, and track changes to user data.
Permission Required
You must declare the "storage" permission in the manifest to use this API.
"permissions": ["storage"]
Stores one or more items in the storage area, or updates existing items.
SYNTAX
chrome.storage.sync.set(items: object, callback?: function)EXAMPLE
// Save data
chrome.storage.sync.set({key: 'value'}, function() {
console.log('Value is set');
});
// Save multiple values
chrome.storage.sync.set({
username: 'John',
age: 30,
preferences: {theme: 'dark'}
}, function() {
console.log('Settings saved');
});Retrieves one or more items from the storage area.
EXAMPLE
// Get single value
chrome.storage.sync.get(['key'], function(result) {
console.log('Value is: ' + result.key);
});
// Get multiple values
chrome.storage.sync.get(['username', 'age'], function(result) {
console.log('Username:', result.username);
console.log('Age:', result.age);
});
// Get all values
chrome.storage.sync.get(null, function(items) {
console.log('All items:', items);
});Removes one or more items from the storage area.
EXAMPLE
// Remove single key
chrome.storage.sync.remove('key', function() {
console.log('Key removed');
});
// Remove multiple keys
chrome.storage.sync.remove(['key1', 'key2'], function() {
console.log('Keys removed');
});Data synced across devices
Limit: 100KB
Local device storage
Limit: 10MB
Session-based storage
Cleared on restart
Use the chrome.tabs API to interact with the browser's tab system. You can use this API to create, modify, and rearrange tabs in the browser.
Gets all tabs that have the specified properties.
EXAMPLE
// Get current active tab
chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
let currentTab = tabs[0];
console.log('Current URL:', currentTab.url);
});
// Get all tabs
chrome.tabs.query({}, function(tabs) {
console.log('Total tabs:', tabs.length);
});
// Get tabs by URL pattern
chrome.tabs.query({url: '*://example.com/*'}, function(tabs) {
console.log('Matching tabs:', tabs);
});Creates a new tab.
EXAMPLE
// Create new tab
chrome.tabs.create({url: 'https://example.com'});
// Create tab with options
chrome.tabs.create({
url: 'https://example.com',
active: true,
pinned: false,
index: 0
}, function(tab) {
console.log('Tab created:', tab.id);
});Modifies the properties of a tab.
EXAMPLE
// Update tab URL
chrome.tabs.update(tabId, {url: 'https://newurl.com'});
// Mute/unmute tab
chrome.tabs.update(tabId, {muted: true});
// Pin/unpin tab
chrome.tabs.update(tabId, {pinned: true});Closes one or more tabs.
EXAMPLE
// Close single tab
chrome.tabs.remove(tabId);
// Close multiple tabs
chrome.tabs.remove([tabId1, tabId2, tabId3]);Use the chrome.windows API to interact with browser windows. You can use this API to create, modify, and rearrange windows.
Creates a new browser window.
EXAMPLE
// Create new window
chrome.windows.create({
url: 'https://example.com',
type: 'popup',
width: 800,
height: 600
});
// Create incognito window
chrome.windows.create({
url: 'https://example.com',
incognito: true
});Gets all windows.
EXAMPLE
chrome.windows.getAll({populate: true}, function(windows) {
windows.forEach(function(window) {
console.log('Window ID:', window.id);
console.log('Tab count:', window.tabs.length);
});
});APIs for user interface interactions
Use the chrome.action API to control the extension's icon in the browser toolbar.
Sets the icon for the extension action.
EXAMPLE
chrome.action.setIcon({
path: {
"16": "images/icon16.png",
"48": "images/icon48.png",
"128": "images/icon128.png"
}
});Sets the badge text for the extension action.
EXAMPLE
// Set badge text
chrome.action.setBadgeText({text: '5'});
// Set badge background color
chrome.action.setBadgeBackgroundColor({color: '#FF0000'});Sets the title of the extension action (tooltip text).
EXAMPLE
chrome.action.setTitle({title: 'Click to activate'});Use the chrome.notifications API to create rich notifications using templates and show these notifications to users.
Creates and displays a notification.
EXAMPLE
chrome.notifications.create({
type: 'basic',
iconUrl: 'icon48.png',
title: 'Notification Title',
message: 'This is the notification message',
priority: 2
}, function(notificationId) {
console.log('Notification created:', notificationId);
});
// Progress notification
chrome.notifications.create({
type: 'progress',
iconUrl: 'icon48.png',
title: 'Download',
message: 'Downloading file...',
progress: 50
});Use the chrome.contextMenus API to add items to the browser's context menu.
Creates a new context menu item.
EXAMPLE
// Create menu item
chrome.contextMenus.create({
id: 'menu1',
title: 'Search with Extension',
contexts: ['selection']
});
// Listen for clicks
chrome.contextMenus.onClicked.addListener(function(info, tab) {
if (info.menuItemId === 'menu1') {
console.log('Selected text:', info.selectionText);
}
});APIs for network requests and cookies
Use the chrome.webRequest API to observe and analyze traffic and to intercept, block, or modify requests in-flight.
Important
This API requires the "webRequest" permission and host permissions for the URLs you want to intercept.
Fired when a request is about to occur.
EXAMPLE
chrome.webRequest.onBeforeRequest.addListener(
function(details) {
console.log('Request to:', details.url);
// Block request
return {cancel: true};
},
{urls: ["*://*.example.com/*"]},
["blocking"]
);Fired before sending an HTTP request.
EXAMPLE
chrome.webRequest.onBeforeSendHeaders.addListener(
function(details) {
// Modify headers
details.requestHeaders.push({
name: 'Custom-Header',
value: 'CustomValue'
});
return {requestHeaders: details.requestHeaders};
},
{urls: ["*://*.example.com/*"]},
["blocking", "requestHeaders"]
);APIs for content script interactions
Use the chrome.scripting API to inject JavaScript and CSS into websites programmatically.
Injects a script into a target context.
EXAMPLE
// Inject script file
chrome.scripting.executeScript({
target: {tabId: tabId},
files: ['content-script.js']
});
// Inject inline script
chrome.scripting.executeScript({
target: {tabId: tabId},
func: () => {
document.body.style.backgroundColor = 'red';
}
});Inserts CSS into a target context.
EXAMPLE
chrome.scripting.insertCSS({
target: {tabId: tabId},
css: 'body { background-color: #f0f0f0; }'
});Removes CSS that was previously inserted.
EXAMPLE
chrome.scripting.removeCSS({
target: {tabId: tabId},
css: 'body { background-color: #f0f0f0; }'
});Frequently used type definitions
{
id: number,
index: number,
windowId: number,
highlighted: boolean,
active: boolean,
pinned: boolean,
url: string,
title: string,
favIconUrl: string,
status: "loading" | "complete",
incognito: boolean,
width: number,
height: number
}{
id: number,
focused: boolean,
top: number,
left: number,
width: number,
height: number,
tabs: Tab[],
incognito: boolean,
type: "normal" | "popup" | "panel" | "app" | "devtools",
state: "normal" | "minimized" | "maximized" | "fullscreen"
}Explore additional resources and join our developer community
Start buying or selling extensions today