Chrome Extension Manifest V3 Reference

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "description": "A short description of what the extension does."
}

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "description": "A Chrome extension built with Manifest V3.",
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png"
    },
    "default_title": "My Extension"
  },
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["storage", "activeTab"]
}

"version": "1.0.0"        // valid
"version": "2.10.3.1"     // valid (4 segments)
"version": "1.01"         // INVALID (leading zero)

"icons": {
  "16": "icons/icon16.png",
  "32": "icons/icon32.png",
  "48": "icons/icon48.png",
  "128": "icons/icon128.png"
}

{
  "permissions": [
    "storage",
    "activeTab",
    "scripting",
    "alarms",
    "contextMenus"
  ],
  "optional_permissions": [
    "bookmarks",
    "notifications"
  ],
  "host_permissions": [
    "https://api.example.com/*"
  ],
  "optional_host_permissions": [
    "https://*.example.com/*"
  ]
}

// Request optional permission at runtime
chrome.permissions.request({
  permissions: ["bookmarks"],
  origins: ["https://api.example.com/*"]
}, (granted) => {
  if (granted) {
    console.log("Permission granted");
  }
});

// Check if permission is already granted
chrome.permissions.contains({
  permissions: ["bookmarks"]
}, (has) => {
  console.log("Has bookmarks:", has);
});

// Remove optional permission
chrome.permissions.remove({
  permissions: ["bookmarks"]
}, (removed) => {
  console.log("Removed:", removed);
});

"background": {
  "service_worker": "background.js",
  "type": "module"
}

// background.js — Service Worker

// Install event
chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === "install") {
    // First install — set defaults
    chrome.storage.local.set({ enabled: true, count: 0 });
  } else if (details.reason === "update") {
    // Extension updated
    console.log("Updated from", details.previousVersion);
  }
});

// Listen for messages from popup or content scripts
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "GET_DATA") {
    chrome.storage.local.get("count", (data) => {
      sendResponse({ count: data.count ?? 0 });
    });
    return true; // Keep message channel open for async response
  }
});

// Alarm for periodic tasks (replaces setInterval)
chrome.alarms.create("daily-check", { periodInMinutes: 60 });
chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === "daily-check") {
    // Do periodic work
  }
});

// Context menu
chrome.contextMenus.create({
  id: "my-menu",
  title: "My Extension Action",
  contexts: ["selection"]
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === "my-menu") {
    chrome.tabs.sendMessage(tab.id, {
      type: "SELECTION",
      text: info.selectionText
    });
  }
});

// Badge updates
chrome.action.setBadgeText({ text: "3" });
chrome.action.setBadgeBackgroundColor({ color: "#22c55e" });

"content_scripts": [
  {
    "matches": ["https://*.example.com/*"],
    "js": ["content.js"],
    "css": ["styles.css"],
    "run_at": "document_idle",
    "all_frames": false,
    "match_about_blank": false,
    "world": "ISOLATED"
  }
]

"content_scripts": [
  {
    "matches": ["https://*.example.com/*"],
    "js": ["content.js"],
    "world": "ISOLATED"   // Default — separate JS context, can use chrome.* APIs
  },
  {
    "matches": ["https://*.example.com/*"],
    "js": ["main-world.js"],
    "world": "MAIN"        // Shares page's JS context, NO chrome.* APIs
  }
]

// Requires "scripting" permission + activeTab or host_permissions
chrome.scripting.executeScript({
  target: { tabId: tabId },
  files: ["content.js"]
});

// Inline function injection
chrome.scripting.executeScript({
  target: { tabId: tabId },
  func: (color) => {
    document.body.style.backgroundColor = color;
  },
  args: ["#1a1a2e"]
});

// Insert CSS
chrome.scripting.insertCSS({
  target: { tabId: tabId },
  css: "body { border: 3px solid red; }"
});

// Or from file
chrome.scripting.insertCSS({
  target: { tabId: tabId },
  files: ["override.css"]
});

// content.js — send message to service worker
chrome.runtime.sendMessage({ type: "PAGE_DATA", url: location.href });

// Listen for messages from service worker
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === "HIGHLIGHT") {
    document.querySelectorAll(msg.selector).forEach(el => {
      el.style.outline = "2px solid #22c55e";
    });
  }
});

// background.js — send to specific tab
chrome.tabs.sendMessage(tabId, { type: "HIGHLIGHT", selector: "h1" });

"action": {
  "default_popup": "popup.html",
  "default_icon": {
    "16": "icons/icon16.png",
    "32": "icons/icon32.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "default_title": "Click to open"
}

"action": {
  "default_popup": "popup.html",
  "default_icon": "icons/icon.png",
  "default_title": "My Extension"
}

// Badge
chrome.action.setBadgeText({ text: "5" });
chrome.action.setBadgeBackgroundColor({ color: "#22c55e" });
chrome.action.setBadgeTextColor({ color: "#ffffff" }); // Chrome 110+

// Title
chrome.action.setTitle({ title: "3 new items" });

// Icon (can use ImageData for dynamic icons)
chrome.action.setIcon({ path: "icons/icon-active.png" });

// Enable/disable
chrome.action.enable(tabId);
chrome.action.disable(tabId);

// Open popup programmatically (user gesture required)
chrome.action.openPopup();

// Listen for clicks (only fires if no popup defined)
chrome.action.onClicked.addListener((tab) => {
  // No default_popup set → handle click here
  chrome.tabs.sendMessage(tab.id, { type: "TOGGLE" });
});

"options_page": "options.html"

"options_ui": {
  "page": "options.html",
  "open_in_tab": true
}

"commands": {
  "_execute_action": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y",
      "mac": "Command+Shift+Y"
    },
    "description": "Open extension popup"
  },
  "custom-command": {
    "suggested_key": {
      "default": "Alt+Shift+G"
    },
    "description": "Run custom action"
  }
}

chrome.commands.onCommand.addListener((command) => {
  if (command === "custom-command") {
    console.log("Custom command triggered");
  }
  // "_execute_action" is handled automatically — opens popup
});

"omnibox": {
  "keyword": "myext"
}

// User types "myext search query" in address bar
chrome.omnibox.onInputChanged.addListener((text, suggest) => {
  suggest([
    { content: text + " option1", description: "First suggestion" },
    { content: text + " option2", description: "Second suggestion" }
  ]);
});

chrome.omnibox.onInputEntered.addListener((text, disposition) => {
  // disposition: "currentTab" | "newForegroundTab" | "newBackgroundTab"
  chrome.tabs.update({ url: "https://example.com/search?q=" + encodeURIComponent(text) });
});

"permissions": ["declarativeNetRequest"],
"declarative_net_request": {
  "rule_resources": [
    {
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules/rules.json"
    }
  ]
},
"host_permissions": [
  "*://*.example.com/*"
]

[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "block"
    },
    "condition": {
      "urlFilter": "||ads.example.com^",
      "resourceTypes": ["script", "image", "xmlhttprequest"]
    }
  },
  {
    "id": 2,
    "priority": 2,
    "action": {
      "type": "redirect",
      "redirect": {
        "url": "https://cdn.example.com/clean.js"
      }
    },
    "condition": {
      "urlFilter": "||tracker.example.com/analytics.js",
      "resourceTypes": ["script"]
    }
  },
  {
    "id": 3,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "X-Custom-Header", "operation": "set", "value": "my-value" }
      ],
      "responseHeaders": [
        { "header": "x-frame-options", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "*://example.com/*",
      "resourceTypes": ["main_frame", "sub_frame"]
    }
  }
]

chrome.declarativeNetRequest.updateDynamicRules({
  addRules: [{
    id: 1001,
    priority: 1,
    action: { type: "block" },
    condition: {
      urlFilter: "||blocked.example.com^",
      resourceTypes: ["script"]
    }
  }],
  removeRuleIds: [1001]  // Remove previous version
});

"web_accessible_resources": [
  {
    "resources": ["images/icon.png", "styles/inject.css"],
    "matches": ["https://*.example.com/*"]
  },
  {
    "resources": ["lib/helper.js"],
    "extension_ids": ["other-extension-id"],
    "matches": [""]
  }
]

// popup.js
chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
  chrome.tabs.sendMessage(tabs[0].id, { type: "ACTION", payload: "go" });
});

// background.js (relay if needed)
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === "RELAY") {
    chrome.tabs.sendMessage(msg.tabId, msg.payload, sendResponse);
    return true;
  }
});

// content.js
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === "ACTION") {
    // Do something on the page
    sendResponse({ success: true });
  }
});

// content.js
chrome.runtime.sendMessage(
  { type: "FETCH_DATA", url: "https://api.example.com/data" },
  (response) => {
    console.log("Got:", response.data);
  }
);

// background.js (has host_permissions for the API)
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === "FETCH_DATA") {
    fetch(msg.url)
      .then(r => r.json())
      .then(data => sendResponse({ data }))
      .catch(err => sendResponse({ error: err.message }));
    return true; // Required for async sendResponse
  }
});

{
  "manifest_version": 3,
  "name": "Side Panel Extension",
  "version": "1.0.0",
  "permissions": ["sidePanel", "activeTab", "storage"],
  "side_panel": {
    "default_path": "sidepanel.html"
  },
  "action": {
    "default_title": "Open Side Panel"
  },
  "background": {
    "service_worker": "background.js"
  }
}

// background.js — Open side panel on action click
chrome.action.onClicked.addListener(async (tab) => {
  await chrome.sidePanel.open({ tabId: tab.id });
});

// defaults.js
const DEFAULTS = {
  theme: "dark",
  enabled: true,
  recentItems: [],
  maxItems: 50
};

// Install defaults
chrome.runtime.onInstalled.addListener(() => {
  chrome.storage.local.get(Object.keys(DEFAULTS), (data) => {
    const missing = {};
    for (const [key, value] of Object.entries(DEFAULTS)) {
      if (!(key in data)) missing[key] = value;
    }
    if (Object.keys(missing).length) {
      chrome.storage.local.set(missing);
    }
  });
});

// Storage change listener
chrome.storage.onChanged.addListener((changes, area) => {
  if (area === "local" && changes.theme) {
    console.log("Theme changed to:", changes.theme.newValue);
  }
});

// Sync storage (synced across devices, 100KB limit)
chrome.storage.sync.set({ theme: "dark" });
chrome.storage.sync.get("theme", (data) => console.log(data.theme));

// Session storage (cleared on browser close)
chrome.storage.session.set({ tempData: "value" });

// Create alarm — minimum period is 1 minute in MV3
chrome.alarms.create("sync", { periodInMinutes: 5 });

// One-time alarm
chrome.alarms.create("delayed-action", { delayInMinutes: 2 });

// Listen
chrome.alarms.onAlarm.addListener((alarm) => {
  switch (alarm.name) {
    case "sync":
      // fetch latest data
      break;
    case "delayed-action":
      // one-time task
      chrome.alarms.clear("delayed-action");
      break;
  }
});

// _locales/en/messages.json
{
  "extName": {
    "message": "My Extension",
    "description": "Extension name"
  },
  "popupTitle": {
    "message": "Click to start",
    "description": "Popup title text"
  },
  "itemCount": {
    "message": "$COUNT$ items found",
    "description": "Shows item count",
    "placeholders": {
      "count": {
        "content": "$1",
        "example": "5"
      }
    }
  }
}

// manifest.json with i18n
{
  "name": "__MSG_extName__",
  "description": "__MSG_extDesc__",
  "default_locale": "en"
}

// In JS
chrome.i18n.getMessage("extName");
chrome.i18n.getMessage("itemCount", "5");

// V2 (string)
"content_security_policy": "script-src 'self'; object-src 'self'"

// V3 (object)
"content_security_policy": {
  "extension_pages": "script-src 'self'; object-src 'self'",
  "sandbox": "sandbox allow-scripts allow-forms; script-src 'self'"
}

// V2 (flat array)
"web_accessible_resources": ["images/icon.png", "lib/inject.js"]

// V3 (array of objects)
"web_accessible_resources": [
  {
    "resources": ["images/icon.png", "lib/inject.js"],
    "matches": ["https://*.example.com/*"]
  }
]