Advanced reference · Advanced

Cosmetic filter syntax

Hide matching page elements with supported CSS and bounded literal text rules.

Overview

A cosmetic rule hides an element on a page. It does not cancel that element’s network requests, delete the underlying information, or establish a website consent choice. Use a network rule when the intended effect is request blocking.

Author narrow selectors and review them in Your Rules. A rule aimed at a broad container can also hide useful controls. Reload the page when checking a change.

Syntax

Scroll sideways to read the whole table.

Purpose Example Expected effect Limitations
Hide by CSS selector on one host news.example##.advertisement Hides elements matching .advertisement on that host and its subdomains. A class-name change can make the rule stop matching.
Hide generally ##.advertisement Offers the selector across websites. Much broader scope; the same class can mean useful content elsewhere.
Exclude a host news.example,~pay.news.example##.advertisement Limits the hide to the included scope while excluding the named subdomain. Commas separate cosmetic host scopes; this differs from network $domain=.
Stop a matching hide news.example#@#.advertisement Excepts the matching selector on that site. It does not allow a blocked network request or disable every cosmetic rule.
Use native CSS relationships news.example##.card:has(.ad-label) Hides a card containing the matching child or descendant according to CSS semantics. Native :has(), :is(), :not() and :where() are passed through as CSS; they do not enable an upstream procedural language.
Match literal text news.example##.card:has-text(Sponsored) Hides matching cards whose text contains that literal. Host scope, a safe selector prefix and a nonempty literal are required; matching is case sensitive and bounded.

Cosmetic entity scopes such as example.*##.advertisement are admitted separately from network scopes. Do not copy that wildcard into a network $domain= option and assume the same support.

Literal text matching

The bounded literal :has-text() form can use ## or #?#. Its corresponding exceptions use #@# or #@?#. An exception must match the selector prefix, operator and literal to stop that procedural hide.

For a simple rule, keep the text operator at the end of the selector. A literal text match is not a regular expression. For example, /Sponsored/ is not a way to request a regex match here; regex :has-text is rejected.

The evaluator intentionally caps candidate work and text reads. A very large element, late candidate or complex page can remain visible even when a human sees the literal somewhere inside it. This is a protection limit, not proof that a broader text rule is needed.

Limits

Shield rejects domainless literal text hides, regex text arguments, multiple text operators and procedural features such as :xpath(), :upward() and :style(). Wrapping a rejected procedural operator inside native :has() does not make it supported. Other selector combinations that cannot be represented exactly are skipped as a whole line.

Do not treat arbitrary HTML filtering, style injection or another blocker’s extended selector catalog as supported CSS. A selector passing the parser still needs to be valid in the browser and match the site’s current markup. Settings such as paused ad hiding, a site pause or a whole-page exception can withhold otherwise valid hides.

Examples

news.example##.advertisement
pay.news.example#@#.advertisement

The first hides the named class in the website scope. The second stops that same hide on the payment subdomain. It does not resume network requests that a separate rule blocked.

For accidental hiding, start with website recovery. Show one hidden control is a narrow recovery aid for an existing hide; it is not an element picker for authoring arbitrary new hiding rules.

Still need help? Contact support