Adblock Plus filters explained

Unfinished, not for translating

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.

/banner/*/img^

This rule blocks:

This rule doesn't block:

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

||ads.example.com^

This rule blocks:

This rule doesn't block:

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.

|http://example.com/|

This rule blocks:

This rule doesn't block:

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 dome domains (here on foo.example.com).

||ads.example.com^$script,image,domain=example.com|~foo.example.info

This rule blocks http://ads.example.com/foo.gif only if the following conditions are met:

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.

@@||ads.example.com/notbanner^$~script

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.

@@||example.com^$document

Comments

Comment

An exclamation mark at the beginning of the rule indicates a comment.

Comment text

This text will not be used for blocking, you can write anything you want.

!This is a comment

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 plugins like Flash or Java
object-subrequest
~object-subrequest
Include or exclude files loaded by browser plugins
subdocument
~subdocument
Include or exclude pages loaded within pages (frames)
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

Less frequently used options, including dtd, ping, xbl, xmlhttprequest, other, collapse, donottrack and match-case are explained in the full documentation.

Element hiding

It is generally recommended that users install the Element Hiding Helper for Adblock Plus to assist them in the generation of element hiding rules.

Domain selection

##selector is used as a placeholder for element selectors.

Example rules Domain selection
##selector

Active on:

  • All domains, including:
  • http://example.com/
  • https://example.net/
  • ftp://example.edu/

Not active on:

  • Not applicable

example.com##selector

Active on, for example:

  • http://example.com/
  • ftp://subdomain.example.com/

Not active on:

  • All other domains, including
  • http://example.edu/
  • ftp://example.net/

~example.com##selector

Active on:

  • All other domains, including
  • http://example.edu/
  • ftp://example.net/

Not active on, for example:

  • http://example.com/
  • ftp://subdomain.example.com/

example.com,example.edu##selector

Active on, for example:

  • http://example.com/
  • https://subdomain.example.com/
  • ftp://example.edu/

Not active on:

  • All other domains, including:
  • http://example.net/

example.com,~mail.example.com##selector

Active on:

  • http://example.com/
  • https://adverts.example.com/

Not active on:

  • http://mail.example.com/
  • All other domains

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 only examples of valid element hiding rules. Any CSS selector supported by Firefox can be used for element hiding.

Extended CSS selectors (Adblock Plus specific)

In some situations standard CSS selectors are not sufficient, for those cases you can also 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