contentSettings Permission

5 min read

contentSettings Permission

What It Grants

Access to the chrome.contentSettings API for controlling per-site content settings (cookies, JavaScript, images, popups, notifications, location, camera, microphone, etc.).

Manifest

{
  "permissions": ["contentSettings"]
}

User Warning

None — this permission does not trigger a warning at install time.

API Access

Each content type is a ContentSetting object with methods:

.get({ primaryUrl, secondaryUrl? }) — get current setting for a URL
.set({ primaryPattern, secondaryPattern?, setting, scope? }) — set for a URL pattern
.clear({}) — clear all custom settings (reset to defaults)
.getResourceIdentifiers() — (for plugins only) list resource identifiers

Content Types

Basic Usage

How to Use contentSettings API

// Check JavaScript setting for a site
const { setting } = await chrome.contentSettings.javascript.get({
  primaryUrl: 'https://example.com/'
});
console.log(`JavaScript: ${setting}`); // "allow" or "block"

// Block JavaScript on a site
await chrome.contentSettings.javascript.set({
  primaryPattern: 'https://example.com/*',
  setting: 'block'
});

// Allow cookies only for session (deleted on browser close)
await chrome.contentSettings.cookies.set({
  primaryPattern: 'https://tracker.com/*',
  setting: 'session_only'
});

// Block all images on a domain
await chrome.contentSettings.images.set({
  primaryPattern: 'https://*.ads.example.com/*',
  setting: 'block'
});

URL Pattern Format

scheme://host/path

*://example.com/* — any scheme, specific host
https://*.example.com/* — all subdomains
https://example.com/* — specific origin
<all_urls> — all URLs

Privacy Control Pattern

import { createStorage, defineSchema } from '@theluckystrike/webext-storage';
import { createMessenger } from '@theluckystrike/webext-messaging';

const schema = defineSchema({ blockedSites: 'string' }); // JSON array
const storage = createStorage(schema, 'sync');

type Messages = {
  BLOCK_SITE: { request: { url: string; types: string[] }; response: { ok: boolean } };
  UNBLOCK_SITE: { request: { url: string }; response: { ok: boolean } };
};
const m = createMessenger<Messages>();

m.onMessage('BLOCK_SITE', async ({ url, types }) => {
  const pattern = `${new URL(url).origin}/*`;
  for (const type of types) {
    const cs = (chrome.contentSettings as any)[type];
    if (cs) await cs.set({ primaryPattern: pattern, setting: 'block' });
  }
  return { ok: true };
});

Scope

// Regular scope — applies to regular browsing
await chrome.contentSettings.cookies.set({
  primaryPattern: 'https://example.com/*',
  setting: 'block',
  scope: 'regular'
});

// Incognito-only scope
await chrome.contentSettings.cookies.set({
  primaryPattern: 'https://example.com/*',
  setting: 'block',
  scope: 'incognito_session_only'
});

When to Use

Privacy/security extensions (block trackers, control permissions)
Parental control extensions
Site-specific preference management
Cookie management tools
JavaScript blocker extensions

When NOT to Use

If you need to block network requests — use declarativeNetRequest
If you need to modify page content — use content scripts
For temporary changes — these persist until cleared

Permission Check

import { checkPermission } from '@theluckystrike/webext-permissions';
const granted = await checkPermission('contentSettings');

Cross-References

Related: docs/permissions/cookies.md, docs/permissions/privacy.md

Frequently Asked Questions

What is contentSettings API used for?

The contentSettings API allows your extension to override settings for cookies, JavaScript, plugins, and other content behaviors on a per-site or global basis.

Can extensions block JavaScript per-site?

Yes, use chrome.contentSettings.javascript.set() to enable or disable JavaScript for specific patterns. —

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

No previous article

No next article