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.

||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.

Still need help? Contact support