BlockIt Rule Syntax

Syntax version 1

BlockIt rules extend CSS selectors with conditions that standard CSS cannot express, or cannot express reliably and conveniently. A rule remains selector-like: start with the CSS part, then add BlockIt pseudo-classes.

div.card:attr-count(=2):has(> span:own-text("Advertisement"))

CSS foundation

Tags, IDs, classes, attributes, selector lists, and standard combinators are supported:

div.notice
#banner
section[data-kind="ad"]
main > section
.anchor + .target
.anchor ~ .target
article, aside

You can use native CSS pseudo-classes supported by the browser. BlockIt extensions can appear inside :has(), :is(), :where(), and :not().

Values and regular expressions

Enclose text values in double quotes, for example :text("Advertisement"). To include a double quote or backslash within a value, put a backslash before it: \" or \\. Pattern-based pseudo-classes accept JavaScript regular expressions, such as /^data-[a-z]+$/i. Position and result numbering starts at one.

Attributes and classes

Syntax	Meaning
`:attr-count(=3)`	Exactly three attributes. Operators: `=`, `<`, `<=`, `>`, `>=`. `:attribute-count()` is an alias.
`:class-count(>=2)`	Number of separate classes.
`:attr-name(/^data-/)`	At least one attribute name matches the regular expression.
`:attr(/^data-/, /^ad-/)`	The name and value of the same attribute match the two regular expressions.
`[data-*]`	An attribute whose name starts with `data-` exists. You can add a condition for the attribute’s value after the name pattern.
`:class-name(/^card-/)`	At least one class matches the regular expression.
`:attrs(["id", /^data-/])`	All listed exact attribute names or name patterns must exist.
`:style-property("--adaptive-width")`	The specified CSS property exists in the inline `style` attribute; its value is ignored.

Text and HTML

Syntax	Meaning
`:text("Advertisement")`	The normalized text of the element and its descendants matches exactly.
`:own-text("Advertisement")`	Only the element’s own normalized text matches exactly.
`:text-starts()`, `:text-ends()`, `:text-contains()`, `:text-matches()`	Prefix, suffix, substring, or regular-expression matching against all text.
`:own-text-starts()`, `:own-text-ends()`, `:own-text-contains()`, `:own-text-matches()`	The same modes, but only for the element’s own text nodes.
`:html(/pattern/)`	The element’s serialized HTML matches the regular expression.

Structure and relationships

Syntax	Meaning
`:has(selector)`	A matching descendant or element of a relative selector exists.
`:within(selector)`	A matching ancestor exists; the search may cross a Shadow DOM host.
`:near(selector)`	A matching sibling exists in either direction, at any distance.
`:sibling-distance(previous, 2, selector)`	The second preceding sibling matches the selector.
`:sibling-distance(next, 3, selector)`	The third following sibling matches the selector.
`:children(selector, >=2)`	The count of matching direct children satisfies the condition.
`:sibling-position(2)`	The element is its parent’s second child.
`:matches-position(2)`	Of all elements found by the complete rule, block only the second. Separate multiple positions with commas or spaces.

Live-page and accessibility conditions

Syntax	Meaning
`:visible(...)`	Checks visibility on the live page.
`:size(...)`	Checks the rendered size.
`:style(...)`	Checks the computed style.
`:property(...)`	Checks a JavaScript DOM property.
`:accessible(...)`	Checks accessibility properties.

These conditions depend on the browser’s current state and may be unavailable when searching a saved DOM snapshot.

Iframe and Shadow DOM

Syntax	Meaning
`:in-frame(...)`	Limits matching to iframe content.
`:in-shadow(...)`	Limits matching to Shadow DOM.
`:frame-has(selector)`	An iframe document contains a match.
`:has-frame(...)`	The element contains an iframe that satisfies the condition.

Cross-origin iframes and closed Shadow Roots are subject to browser and extension-permission limitations.

Rule examples

The examples below show how to combine ordinary CSS with BlockIt conditions. A rule can contain several conditions at once: an element matches only when all of them are satisfied.

Ordinary CSS selectors

Rule	What it finds
`article.card[data-type="advertisement"]`	`<article>` elements with the `card` class and a `data-type` attribute whose exact value is `advertisement`. Other classes and attributes do not prevent a match.
`main > aside.promo, section[data-kind="sponsor"]`	Either direct `<aside class="promo">` children of `<main>`, or any `<section>` with the specified attribute.

Attributes and classes

Rule	What it finds
`[data-*]`	Elements with any attribute whose name starts with `data-`, such as `<div data-zone="sidebar">`. The attribute may have any value.
`[data-*="advert"]`	Elements with at least one `data-*` attribute whose value is exactly `advert`, such as `<aside data-kind="advert">`.
`[data-*^="ad-"]`	Elements whose value for at least one `data-*` attribute starts with `ad-`, such as `<div data-slot="ad-top">`.
`[data-*$="-banner"]`	Elements whose value for at least one `data-*` attribute ends with `-banner`, such as `<section data-kind="top-banner">`.
`[data-**="advert"]`	Elements whose value for at least one `data-*` attribute contains `advert`, such as `<div data-label="sidebar advertisement">`.
`div:attr-count(=3):class-count(>=2)`	`<div>` elements with exactly three attributes and at least two separate classes.
`section:attrs(["id", /^data-/])`	`<section>` elements that have both an `id` attribute and at least one attribute whose name starts with `data-`.
`div:attr(/^data-/, /^ad-/)`	`<div>` elements where the same attribute has a name starting with `data-` and a value starting with `ad-`.

Text and HTML

Rule	What it finds
`button:own-text("Close")`	Buttons whose own normalized text is exactly “Close”. Text inside nested elements is ignored.
`div.notice:text-contains("Disable your ad blocker")`	`<div class="notice">` elements whose complete text, including descendants, contains that phrase.
`article:html(/data-slot="ad-[^"]+"/i)`	`<article>` elements whose serialized HTML contains a `data-slot` attribute with a value starting with `ad-`. Matching is case-insensitive.

Structure, relationships, and positions

Rule	What it finds
`section:has(> div:attr-count(=2) > span:own-text("Advertisement"))`	`<section>` elements with a direct `<div>` child that has exactly two attributes and contains a direct `<span>` child whose own text is “Advertisement”.
`div.card:within(main.content):near(div.promo)`	`<div class="card">` elements inside `<main class="content">` that have a `<div class="promo">` sibling.
`div.target:sibling-distance(previous, 2, div.new-menu)`	`<div class="target">` elements whose second preceding sibling matches `div.new-menu`.
`ul:children(li, >=3)`	`<ul>` lists with at least three direct `<li>` children.
`article.card:matches-position(2, 4)`	The second and fourth elements among all results found by `article.card`.

Page state and accessibility

Rule	What it finds
`button:visible():accessible(role="button", name=/close/i)`	Visible buttons with the `button` role whose accessible name contains “close”, ignoring case.
`div.banner:size(width>=300, height<250):style(display, "block")`	`<div class="banner">` elements at least 300 pixels wide, less than 250 pixels high, and with a computed `display: block` value.
`div:style-property("--adaptive-width")`	`<div>` elements whose inline `style` declares `--adaptive-width`; its value may be anything.
`input:property(disabled, "false")`	`<input>` elements whose JavaScript `disabled` property has the string representation `false`.

Iframe and Shadow DOM

Rule	What it finds
`*:in-frame(/docs\.example\.com/)`	Elements inside an iframe whose URL matches the regular expression.
`button:in-shadow(video-player)`	Buttons inside a Shadow DOM whose host matches `video-player`.
`iframe:frame-has(button:own-text("Close"))`	`<iframe>` elements whose document contains a button with the own text “Close”.
`div.viewer:has-frame(> iframe, button:own-text("Close"))`	`<div class="viewer">` elements with a direct iframe child containing a button whose own text is “Close”.

Compatibility

Saved rules will continue to work after BlockIt updates. New capabilities may be added without changing the meaning of existing syntax.