Advanced reference · Advanced
Network filter syntax
Use the verified network-rule subset and understand exceptions, scopes and rejected lines.
Overview
Shield accepts a bounded subset of the filter language shared by many blocking lists. It skips a line it cannot represent faithfully. Removing an unfamiliar option to make a line pass can change its meaning; read the preview instead.
The examples below use reserved example domains. They describe rule behavior, not rules you should install for a real service. Put one line at a time in Your Rules, review its scope, and apply only the change you intend.
Syntax
URL patterns
Scroll sideways to read the whole table.
| Purpose | Syntax and example | Expected effect and limits |
|---|---|---|
| Match a host | ||ads.example^ |
Matches that host and its subdomains at a hostname boundary; it does not match notads.example. An untyped rule targets ordinary requests, not top-level page navigation. |
| Anchor a URL | |https://cdn.example/ads.js| |
Requires the URL to begin and end at those positions. A changed scheme, path or query can stop the match. |
| Match part of a URL | /ad/image/*$image |
Matches image-request URLs containing the named path followed by variable text. The trailing wildcard distinguishes it from a slash-delimited regular expression. |
| Use a wildcard | ||cdn.example/ads/* |
* matches variable text; ^ matches a separator or URL end. Multi-wildcard patterns have admission and work limits; arbitrarily large patterns are not accepted. |
Patterns use ASCII URL text. Do not include a #fragment: the browser does not send URL fragments as part of a network request.
Types, parties and website scopes
Scroll sideways to read the whole table.
| Purpose | Example | Expected effect and limits |
|---|---|---|
| Restrict a request type | ||ads.example^$script |
Applies to scripts. Other types include image, stylesheet, font, media, object, xmlhttprequest, subdocument, document, ping, websocket and other. Aliases include css, xhr, frame and doc. |
| Exclude a type | ||ads.example^$~image |
Excludes images. A negated-only rule still excludes top-level documents; it does not turn into a page-blocking rule. |
| Include all types | ||ads.example^$all |
Explicitly includes top-level documents. $all,~script includes the other modeled types. Use with care. |
| Restrict party | ||ads.example^$third-party |
Applies when the request is third party relative to its initiating site. 3p is an alias; first-party, 1p, ~third-party and ~3p select first party. |
| Restrict the initiating website | ||ads.example^$domain=news.example |
Restricts matching to requests initiated by that host. Excluded initiating hosts can be added as shown below. Entity wildcards in network $domain= scopes are rejected. |
An include/exclude scope uses | between hostnames and ~ before an excluded host:
||ads.example^$domain=news.example|~pay.news.example
Exceptions and priority
@@||ads.example^$script,domain=shop.example allows matching script requests initiated by the named website. It does not pause all protection on that website.
An ordinary matching exception beats an ordinary block. An $important block beats an ordinary exception; an exception carrying $important beats that important block. More-specific-looking text is not a general priority system.
For a whole-page exception, @@||shop.example^$document disables protection for a matching top-level page and its loads. This form cannot add a party condition, initiating-domain scope, extra resource types or $all. Non-exception $document is a top-level document block, not a pause.
@@||news.example^$generichide stops general cosmetic hiding on that host. It leaves site-specific cosmetic rules and request blocking available. Only an exception on a pure host anchor is admitted; paths, party conditions and other type scopes do not carry through this host-only form.
Popup destinations
||popups.example^$popup matches popup navigation destinations using Shield’s popup handler. @@||accounts.example^$popup,domain=shop.example is a scoped popup exception. These are not script-request rules and do not configure the browser’s built-in popup blocker.
Do not combine $popup with request types, $all, $generichide or a redirect action: one line cannot represent both scopes. For a sign-in window problem, start with sign-in and payment windows.
Hosts files and conditional blocks
Canonical hosts entries using sink addresses 0.0.0.0, 127.0.0.1, ::1, :: or 0 are translated into host-anchor rules. For example, 0.0.0.0 ads.example becomes the equivalent of ||ads.example^. Other whitespace-separated network shapes are rejected.
Lists may use nested !#if, !#else and !#endif with !, &&, || and parentheses. Conditions are evaluated for Shield’s package target. Recognized true shared conditions include true, env_mv3 and cap_user_stylesheet; env_chromium and env_firefox depend on the target. Unknown constants evaluate false. These directives select list branches, not live page conditions.
Inert redirects
A closed resource set is accepted: redirect=noopjs or redirect=noop.js supplies an empty script; redirect=nooptext or redirect=noop.txt supplies empty text; redirect=noopjson supplies {}. For example, ||ads.example/tracker.js$script,redirect=noopjs substitutes the inert script when the rule wins.
These are packaged substitutions, not arbitrary URL redirects or full emulations of a third-party library. Unknown resource names and redirect actions on exception rules are rejected. A competing hard block at the same priority can win over a redirect.
Limits
Regex network filters, removeparam, csp, badfilter, redirect-rule and unknown modifiers are rejected as whole lines. This reference does not promise compatibility with every EasyList, uBlock Origin or AdGuard feature. Missing syntax here is not proof that it was tested and rejected.
Accepted rules can still exceed browser capacity or be overridden by protection settings and exceptions. Check the preview and protection status; a configured rule is not proof of a page effect.
Examples
A narrow block and exception pair:
||ads.example^$script,third-party
@@||ads.example^$script,domain=checkout.example
The first blocks matching third-party scripts. The second permits matching script requests initiated by checkout.example. Test the website’s actual workflow after reloading; an allowed request can also allow advertising or tracking.