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.