Why Create Custom Filters?
While AdGuard's built-in filter lists do an excellent job of blocking most ads and trackers, there are situations where you need more control. Perhaps a specific website has elements that annoy you but are not covered by any existing list. Maybe a filter rule is blocking something you actually need. Or perhaps you manage a network and want to enforce custom blocking policies. Custom filter rules give you that power.
Writing your own filter rules might sound intimidating, but the syntax is logical and well-documented. In this guide, we will cover everything from basic blocking rules to advanced cosmetic filters and scriptlets.
Understanding Filter Rule Syntax
AdGuard uses a filter rule syntax that is compatible with the Adblock Plus format but extends it with many additional features. Every rule is a single line of text that tells AdGuard what to block, hide, or modify.
Basic URL Blocking Rules
The simplest type of rule blocks a specific URL or URL pattern. Here are the fundamental patterns:
||example.com^- Blocks all requests to example.com and its subdomains||ads.example.com^- Blocks requests specifically to ads.example.com/banner/- Blocks any URL containing "/banner/" in its path||example.com/ads/*- Blocks URLs matching the pattern on example.com
The || prefix matches the beginning of a URL regardless of protocol (http or https). The ^ character is a separator that matches anything except a letter, digit, or certain special characters.
Exception Rules
If a blocking rule is too aggressive and blocks something legitimate, you can create an exception using the @@ prefix:
@@||cdn.example.com/required-script.js- Allows this specific script even if other rules would block it@@||example.com^$document- Disables all filtering on example.com
Cosmetic Rules: Hiding Page Elements
Cosmetic rules (also called element hiding rules) use CSS selectors to hide elements on a page without blocking the network request. These are essential for removing elements that are served from the same domain as legitimate content.
Basic Element Hiding
The syntax for cosmetic rules uses ## to separate the domain from the CSS selector:
example.com##.ad-banner- Hides elements with class "ad-banner" on example.comexample.com###sidebar-ad- Hides the element with id "sidebar-ad" on example.comexample.com##div[data-ad="true"]- Hides divs with a specific data attribute##.cookie-popup- Hides elements with class "cookie-popup" on all websites
Advanced CSS Selectors
AdGuard supports extended CSS selectors that go beyond standard CSS. These are incredibly powerful for targeting elements that are difficult to select with standard selectors:
example.com##div:has(> .ad-label)- Hides divs that contain a child with class "ad-label"example.com##p:contains(Sponsored)- Hides paragraphs containing the text "Sponsored"example.com##div:matches-css(position: fixed)- Hides fixed-position divs
Caution: Extended CSS selectors are more resource-intensive than standard selectors. Use them sparingly and only when standard CSS cannot achieve the desired result. Overusing extended selectors can slow down page rendering.
Modifiers: Fine-Tuning Your Rules
Modifiers are added to rules using the $ character and allow you to refine when and how a rule is applied:
| Modifier | Description | Example |
|---|---|---|
$third-party | Only match third-party requests | ||tracker.com^$third-party |
$script | Only match script resources | ||ads.com^$script |
$image | Only match image resources | ||ads.com^$image |
$domain=example.com | Only apply on specific domain | /ads/$domain=example.com |
$important | Override exception rules | ||malware.com^$important |
$popup | Block popup windows | ||spam.com^$popup |
DNS Filtering Rules
If you are using AdGuard Home or AdGuard DNS, you can write DNS-level filtering rules. These are simpler than browser-level rules because they operate at the domain level only:
||ads.example.com^- Blocks the domain at DNS level@@||allowed.example.com^- Excepts a domain from blocking0.0.0.0 ads.example.com- Hosts-file format (also supported)/^ad[0-9]+\\.example\\.com$/- Regular expression rules for pattern matching
Organizing Your Custom Rules
As your custom rule list grows, organization becomes important. Here are best practices for maintaining your rules:
- Add comments - Use
!at the beginning of a line to add a comment explaining what the rule does - Group related rules - Keep rules for the same website together
- Date your rules - Add the date when you created a rule so you can review old ones
- Test before committing - Use the filtering log to verify your rules work as expected
- Review periodically - Websites change, and old rules may become unnecessary or broken
Example of a Well-Organized Custom List
A properly organized custom filter list starts with metadata headers including the title, description, last modified date, and homepage. Then rules are grouped by website with comments explaining each section. This approach makes maintenance much easier, especially if you share your filter list with others or come back to modify it months later.
Sharing and Subscribing to Custom Lists
If you have created a useful set of custom rules, you can share them with others by hosting the file online (for example, on GitHub). Other AdGuard users can then subscribe to your list by adding the URL in their filter list settings. This is how community filter lists like EasyList and Fanboy's Annoyances became popular. Many of AdGuard's own filter lists started as community contributions.
Common Pitfalls to Avoid
- Overly broad rules - A rule like
/adwill block URLs containing "ad" anywhere, including "download" and "upload". Be specific. - Forgetting the separator - Always use
^after domain names to prevent matching substrings of other domains - Too many cosmetic rules - Each cosmetic rule runs on every page load. Keep your list lean.
- Not testing on multiple sites - A rule that works on one site might break another. Test broadly.
Creating custom filter lists is a skill that improves with practice. Start with simple rules, use the filtering log to test and refine, and gradually work your way up to more complex patterns. With time, you will have a personalized filter list that gives you exactly the browsing experience you want.
