Safari Content Blocker Resource Triggers Explained

This article provides a comprehensive overview of the specific resource triggers that Safari Content Blockers can target to filter web traffic, enhance privacy, and improve page load speeds. By utilizing WebKit's content-blocking architecture, developers can define JSON rules that instruct the Safari browser to block, ignore, or modify network requests based on the exact type of web asset being requested, ranging from standard images and style sheets to background scripts and pop-up windows.

In Safari, content blockers operate using a declarative JSON format. Each rule contains a trigger object and an action object. Within the trigger object, developers can specify a resource-type array. If this array is omitted, the rule applies to all resource types. When specified, the content blocker will only evaluate the rule if the requested network asset matches one of the defined strings.

Here are the specific resource triggers a Content Blocker can target in Safari:

Visual and Layout Resources

  • image: Targets standard image files loaded by the webpage, such as JPEG, PNG, GIF, and WebP formats. This is typically used to block banner ads, tracking pixels, and heavy visual content.
  • style-sheet: Targets Cascading Style Sheets (CSS). Blocking a style sheet prevents the browser from downloading external styling rules, though developers more commonly use the css-display-none action to hide specific page elements rather than blocking the entire CSS file.
  • font: Targets custom web fonts (such as WOFF, WOFF2, or TTF files). Blocking third-party font requests can significantly speed up page rendering and prevent font-based fingerprinting.
  • svg-document: Targets Scalable Vector Graphics (SVG) when they are loaded as an independent document, such as inside an <object> or <embed> tag, rather than inline HTML.
  • media: Targets audio and video files loaded through HTML5 <audio> and <video> elements. This is commonly used to stop auto-playing video advertisements and reduce bandwidth consumption.

Functional and Executable Resources

  • script: Targets executable code, primarily JavaScript files. Because most web trackers, analytics, and dynamic advertisements rely on JavaScript to function, the script trigger is one of the most heavily utilized resource types in privacy-focused content blockers.
  • raw: Targets untyped network loads. In practice, this applies to asynchronous background requests made via XMLHttpRequest (XHR), the Fetch API, and WebSockets. Targeting raw resources is essential for blocking dynamic data collection and single-page application (SPA) ad injections.
  • ping: Targets network requests initiated by the ping attribute on HTML anchor (<a>) tags and Navigator.sendBeacon() calls. Websites use these exclusively for click-tracking and analytics, making them a primary target for privacy extensions.

Document and Navigation Resources

  • document: Targets the main HTML document of the webpage being loaded, as well as sub-documents loaded inside <iframe> or <frame> elements. Blocking a document stops the entire page or iframe from loading.
  • popup: Targets requests that attempt to open a new browser window or tab. When paired with a block action, this trigger prevents intrusive pop-up and pop-under advertisements from spawning when a user interacts with a page.

By combining these resource triggers with other parameters—such as url-filter (matching specific URLs) and load-type (distinguishing between first-party and third-party requests)—Safari Content Blockers can precisely eliminate unwanted web components without breaking the core functionality of the websites a user visits.