Adblock Plus filters explained
Please note: This cheatsheet is outdated. Please read the current documentation in our Help Center here.
Simple blocking rules
Blocking rules determine addresses that Adblock Plus should block.
Example 1: Blocking by address parts
Verbatim text
This text must be present in the address to be blocked.
Wildcard character
This stands for any number of characters.
Separator
The address must either end here or a separator character like ? or / has to follow.
This rule blocks:
http://example.com/banner/foo/imghttp://example.com/banner/foo/bar/img?paramhttp://example.com/banner//img/foo
This rule doesn't block:
http://example.com/banner/imghttp://example.com/banner/foo/imgraphhttp://example.com/banner/foo/img.gif
Example 2: Blocking by domain name
Domain name anchor
The following text must be the domain name of the address.
Verbatim text
This text must be present in the address to be blocked.
Separator
A separator character has to follow that will indicate the end of the domain name, e.g. / or :.
This rule blocks:
http://ads.example.com/foo.gifhttp://server1.ads.example.com/foo.gifhttps://ads.example.com:8000/
This rule doesn't block:
http://ads.example.com.ua/foo.gifhttp://example.com/redirect/http://ads.example.com/
Example 3: Blocking exact address
Start anchor
The following text must be the beginning of the address.
Verbatim text
This text must be present in the address to be blocked.
End anchor
The preceding text must be the end of the address.
This rule blocks:
http://example.com/
This rule doesn't block:
http://example.com/foo.gifhttp://example.info/redirect/http://example.com/
Options in blocking rules
Blocking rules can have a number of options to fine-tune their behavior.
Address to be blocked
This part of the rule defines which addresses it is applied to.
Option separator
This character indicates that the following text defines filter option.
Type option
Type options define request types to be blocked. Common type options are
script or image indicating that only
scripts/images should be blocked. The inverse type option ~script
means that the filter should not be applied to scripts.
Domain option
Domain option restricts the filter to a set of domains (here example.com).
It also allows to disable the rule on some domains (here on foo.example.com).
This rule blocks http://ads.example.com/foo.gif only if the following conditions are met:
- This address is being loaded as a script or an image.
-
The page loading it comes from
example.comdomain (for exampleexample.comitself orsubdomain.example.com) but not fromfoo.example.comor its subdomains.
Exception rules
Exception rules are built the same as blocking rules, they define which addresses should be allowed even if matching blocking rules exists.
Example 1: Exception for particular requests
Exception rule
Rules starting like this are exceptions, they will override blocking rules.
Address to be allowed
This part of the rule defines which addresses it is applied to, it is structured the same as for blocking rules.
Type option
This type option prevents the exception from being applied to scripts.
Example 2: Exception for an entire site
Exception rule
Rules starting like this are exceptions, they will override blocking rules.
Address to be allowed
This part of the rule defines which addresses it is applied to, it is structured the same as for blocking rules.
Type option
This special type option indicates that Adblock Plus should be completely disabled on pages that this rule applies to.
Comments
Comment text
This text will not be used for blocking, you can write anything you want.
Filter options
| Option | Purpose |
|---|---|
| Types | |
script~script |
Include or exclude JavaScript files |
image~image |
Include or exclude image files |
stylesheet~stylesheet |
Include or exclude stylesheets (CSS files) |
object~object |
Include or exclude content handled by browser plug-ins like Flash or Java |
subdocument~subdocument |
Include or exclude pages loaded within pages (frames) |
xmlhttprequest~xmlhttprequest |
Include or exclude requests started using the XMLHttpRequest object or fetch API |
websocket~websocket |
Include or exclude requests initiated via WebSocket object |
webrtc~webrtc |
Include or exclude connections opened via RTCPeerConnection instances to ICE servers |
popup |
Include pages opened in a new tab or window |
generichide |
Used to prevent applying global element rules on a page (e.g. @@||example.com^$generichide) |
genericblock |
Used to prevent applying global blocking rules on a page (e.g. @@||example.com^$genericblock) |
| Exceptions | |
document |
Used to whitelist the page itself (e.g. @@||example.com^$document) |
elemhide |
Used to prevent element rules from applying on a page (e.g. @@||example.com^$elemhide) |
| Domains | |
domain= |
Specify a list of domains, separated by bar lines (|), on which a filter should be active. A filter may be prevented from being activated on a domain by preceding the domain name with a tilde (~). |
third-party~third-party |
Specify whether a filter should be active on third-party or first domains |
| Misc | |
Less frequently used options, including ping, other and match-case are explained in the Writing Adblock Plus Filters documentation.
Element hiding
Example 1: Hiding elements
We want to hide elements with class the advert on example.net, example.com and subdomains.
Domains
An optional comma separated list of domains this filter applies to. If ommitted, it applies everywhere.
Separator
For an element hiding filter using standard CSS selectors, the separator is ##.
Selector
The CSS selector for the elements to hide.
Example 2: Exception in element hiding
We want to exclude the above hiding rule on exception.example.com.
Domains
Comma separated list of domains this exception applies to. This can be ommitted.
Exception separator
For an element hiding filter exception using CSS selectors, the separator is #@#.
Selector
The CSS selector matching the rule we want to create an exception for.
Domain selection
##selector is used as a placeholder for element selectors.
| Example rules | Domain selection |
|---|---|
##selector |
Active on:
Not active on:
|
example.com##selector |
Active on, for example:
Not active on:
|
~example.com##selector |
Active on:
Not active on, for example:
|
example.com,example.edu##selector |
Active on, for example:
Not active on:
|
example.com,~mail.example.com##selector |
Active on:
Not active on:
|
Element selection
| Selector | Purpose |
|---|---|
###advert |
Matches the element with the unique id "advert" |
##.advert |
Matches elements with the class "advert" |
##table[height="100"][width="100"] |
Matches a table with a height of 100 and a width of 100 |
##a[href="http://example.com/"] |
Matches links to http://example.com/ |
##div[style="width:300px;height:250px;"] |
Matches div elements that have exactly the style specified |
###advert > .link |
Matches elements with the class "link" that are enclosed within elements with the id "advert" |
###advert + .link |
Matches elements with the class "link" that are immediately preceded by elements with the id "advert" |
##a[href^="http://example.com/"] |
Matches links to any pages hosted on http://example.com/ |
##div[style^="width:300px;height:250px;"] |
Matches div elements that start with the style specified |
##div[style$="width:300px;height:250px;"] |
Matches div elements that end the style specified |
##div[style*="width:300px;height:250px;"] |
Matches div elements that containing the style specified |
The above filters are examples of valid element hiding rules. Any CSS selector supported by your browser can be used for element hiding.
Extended CSS selectors (Adblock Plus specific)
In some situations standard CSS selectors are not sufficient. For those cases there are extended CSS pseudo-selectors, and the filter syntax differs from the element hiding by using an alternate separator.
Example 1: Hiding element based on their content
Hide div elements that contain a div that contain an image with CSS class advert.
Domains
Comma separated list of domains this filter applies to. This is mandatory.
Separator
For an element hiding filter using extended CSS pseudo-selectors, the separator is #?#.
Selector
The CSS selector to select the elements to hide. It can use the extended selectors syntax.
Example 2: Exception for the element hiding
Domains
Comma separated list of domains this exception applies to.
Exception Separator
Like for an element hiding filter, the separator for an exception is #@#.
Selector
The CSS selector matching the rule we want to create an exception for.
Adblock Plus specific pseudo-selectors
You can use the following Adblock Plus specific pseudo-selectors:
| Pseudo-class | Purpose |
|---|---|
:-abp-properties() |
Select an element if its CSS style properties match what's specified. You can pass a regular expression by surrounding it with "/". |
:-abp-has() |
Select an element if its content subtree match the selector specified |
:-abp-contains() |
Select an element if its text content contains the specified string |
When writing element hiding filters that make use those you must use the #?# syntax (replace ## with #?#) and take care to specify one or more domains. Some examples:
| Selector | Purpose |
|---|---|
example.com#?#div:-abp-properties(width:300px;height:250px;) |
Matches div elements whose style contain the specified properties |
example.com#?#div:-abp-has(> div > img.advert) |
Matches div elements that contain as a direct descendant a div element whose direct descendant is an img with the class "advert" |
example.com#?#div:-abp-has(> div > img:-abp-properties(width:300px;height:250px;)) |
Matches div elements that contain as a direct descendant a div element whose direct descendant is an img element whose style properties contain the specified properties, a width of 300 pixels and an height of 250 pixels |
example.com#?#div:-abp-has(> div > img:-abp-properties(WidTh:300px;hEigHt:250px;)) |
Since the CSS properties are matched case-insensitively, this filter matches the same thing as above |
example.com#?#div:-abp-has(> span:-abp-contains(Advertisment)) |
Matches div elements that have a direct descendent span element containing the text "Advertisment" |
example.com#?#div > img:-abp-properties(width:*px;height:250px;) |
By using a wildcard *, this filter matches an img whose CSS style properties have a width specified in pixels and a height of 250 pixels |
example.com#?#div > img:-abp-properties(/width: 3[2-8]px;/) |
By using a regular expression, this filter matches an img whose CSS style properties have a width between 32 and 38 pixels |
Snippet filters
Snippet filters allow executing snippet scripts.
Domains
Comma separated list of domains this filter applies to.
Separator
For a snipet filter, the separator is #$#.
Script
The snippet script.
Comment
An exclamation mark at the beginning of the rule indicates a comment.