BlockIt User Guide

What is BlockIt?

BlockIt helps you create rules for specific page elements and understand why a rule finds them. The builder shows which traits of the element and its surroundings are used for matching. You can check whether those traits distinguish the target from other elements well enough and choose the ones you consider stable.

Key features

• Flexibility:
  • You decide whether to remove an element or hide it
  • You decide which elements to block and which to keep
  • You decide which rules to keep, disable, or delete
  • Both CSS selectors and XPath expressions are supported
  • Rules also apply inside iframes and Shadow DOM
• Privacy: all rules are stored locally in your browser and are not sent anywhere.
• BlockIt syntax: complex cases can use syntax that extends standard CSS selectors. See the BlockIt syntax documentation when needed.
• Rules grouped by site: rules are automatically grouped for the current site and for all other sites, making them easier to manage.
• Share settings: export your rules to a file to share them with other users.
• Multiple languages: the extension follows your browser language. Russian, English, French, German, Spanish, Portuguese, Chinese, and Japanese are supported. If your language is unavailable, the interface is shown in English.
• Open source: the extension is developed under the BSD-3-Clause license. You can contribute, suggest improvements, and inspect the code on GitHub.

Quick start Back to top

Use this route when you want to start with a ready-made CSS selector from DevTools.

The DevTools interface in the screenshots is in English. You can change the DevTools interface language.

Customize DevTools Optional

How to open DevTools

Action	Result
F12	Opens DevTools.
Ctrl + Shift + I	Opens the same panel.
Right-click an element → “Inspect”	Opens DevTools with that element highlighted.

Interface language

1. Open DevTools.
2. Click the gear ⚙ in the upper-right corner to open Settings.
3. Open the Preferences tab.
4. Choose a language under Language.
5. Close and reopen DevTools.

Panel placement

Click ⋮ in the upper-right corner of DevTools and choose a position under Dock side: right, bottom, left, or a separate window. Docking on the right is usually convenient on a wide monitor, docking at the bottom when vertical space is available, and a separate window when using two screens.

‹

›

1

‹

›

1

Blocking modes

• Remove: the element disappears from the page, and its space is usually freed. Content below it may shift.
• Hide: makes the element invisible while preserving its space. Use this if removing it makes the page look worse.

The rule usually takes effect immediately. If the element remains visible, reload the page.

Ways to create a rule Back to top

First find the element in DevTools and inspect its tag, classes, and attributes.

1Copy a CSS selector from DevTools Select to read

Start here to quickly test whether a standard selector can block the element. DevTools creates it automatically: select the element, then choose “Copy” → “Copy selector”.

Paste the selector into BlockIt’s main field, check the match count, and add the rule. If it becomes unreliable after a refresh, use StableHTMLFinder or the rule builder.

‹

›

1

2Copy XPath from DevTools Select to read

XPath describes a path to an element through the page structure. It can help when classes and other attributes are unstable but the path itself remains unchanged. Choose “Copy XPath” in DevTools, then paste the expression into BlockIt’s main field.

Inspect the copied expression. Chrome may build an XPath around an id. If that ID changes, the XPath is unstable too. An absolute path with position numbers will break when the HTML structure changes.

BlockIt evaluates XPath separately in the main document and in each iframe, so an XPath copied from inside an iframe may work. Browsers do not evaluate XPath across a Shadow DOM boundary. In that case, use the rule builder or StableHTMLFinder to create a CSS-based or extended BlockIt rule.

‹

›

1

3Create a quick rule from HTML Select to read

This method gives you more control than a ready-made DevTools selector: after parsing the HTML, you choose which attributes go into the selector.

‹

›

1

Do not keep every attribute automatically. A class or ID made of random-looking characters may change on the next page load.

4Use StableHTMLFinder Select to read

Install StableHTMLFinder from the Chrome Web Store

Detailed guide: StableHTMLFinder instructions.

StableHTMLFinder helps when classes and IDs are obfuscated, change between loads, or the page contains many similar blocks. It is often easier than inspecting HTML manually, but analysis takes time because the extension must load the page several times.

‹

›

1

StableHTMLFinder does not block elements itself. It helps you choose a foundation for a BlockIt rule:

• CSS selector — the simplest option when it uses stable traits and finds the correct number of elements.
• BlockIt rule — use this when precise matching needs extended syntax unavailable in standard CSS.
• Inspect the map yourself — study stable traits of the element and its surroundings, then enter them in the BlockIt rule builder. Use this when the generated results are not precise enough.

5Open the rule builder Select to read

The rule builder is a powerful tool for creating precise rules without knowing CSS, XPath, or BlockIt syntax. It works for both stable and unstable elements: a rule can use text, attribute or class counts, sibling position, and surrounding elements instead of a specific class.

Copy the element’s HTML in DevTools, open BlockIt’s “Advanced mode,” paste the HTML into the corresponding field, and click “Open rule builder.”

Element card

Each card describes one HTML element: its tag, attribute count, and conditions based on attributes, text, and position.

Relationship tree

Ancestors appear above. Descendants appear below with an indent. Siblings are shown at the same nesting level.

Stable traits

You can disable automatically inserted values. Do not use changing IDs and classes merely because they were found in the HTML.

Testing

Check the match count immediately, then use “Check after refresh” to verify that the result remains stable.

Which traits can you set in an element card?

Whenever possible, keep only the traits that are necessary and reasonably stable. If you want to check matches in DevTools, use traits that the builder can express as a regular CSS selector. The label next to the preview tells you what was generated: “CSS selector” or “BlockIt rule.”

• Tag, classes, and attributes: a tag, individual classes, and ordinary conditions on attribute names and values can usually be expressed as CSS selectors. Attribute names can be matched exactly; supported CSS value operators include exact match, starts with, ends with, and contains.
• Attribute and class counts: set an exact, minimum, or maximum count. These counts cannot be checked with an ordinary CSS selector and require BlockIt syntax.
• Text: the element’s own text or text inside it, including an exact match, prefix, suffix, substring, or regular expression. CSS does not select elements by text, so this condition requires BlockIt.
• Partial class-name matching, regular expressions, and attribute-name patterns: these conditions also require BlockIt; CSS selectors cannot test regular expressions.
• Sibling position: an element’s position among one parent’s children can be expressed with a CSS pseudo-class such as :nth-child(). Selecting a position among the matches of the whole rule is a separate BlockIt feature.
• Related elements and sibling distance: some relationships can be expressed as CSS, while other combinations of relationships and conditions require BlockIt. A distance of 0 means an immediately adjacent sibling.

If the preview says “BlockIt rule,” you cannot test it as CSS in DevTools. Add such traits when they are needed to make the rule precise. You can enter the rule in StableHTMLFinder’s stability-map search to see which mapped elements match it. A CSS selector, on the other hand, can be copied and tested in DevTools.

Related elements

You can add a direct parent or any ancestor to the target and its ancestors. The target can also have a child, descendant, or sibling; siblings can have descendants of their own. The distance to a sibling can be taken into account when needed. Related elements have an “May be absent” switch.

Sibling position is an element’s place among children of one parent. Position in rule results is its place among all elements found by the complete rule. These are different conditions.

Preview and testing

Read the plain-language description in “Rule preview.” It helps reveal an attribute, text condition, or relationship that was included by accident. Then check the match count on the current page and after a refresh.

Example: configuring one rule for several elements

1. Enable “Sibling position” and enter the positions of the required elements: 2, 3, and 5 in this example.
2. Keep exact matching for the class attribute name.
3. Remove the unreliable part of the class value and change “value: exactly” to “value: contains”.
4. Disable “Class count” if that number is not significant and may change.
5. Read the description under “Rule preview” and check that every condition is necessary.
6. Close DevTools on the target page and click “Check after refresh.” Some sites load different content while DevTools is open.
7. Make sure the number of matches does not change after the refresh. This indicates that the rule is stable.
8. Click “Create rule.”

‹

›

1

When to switch methods

Start with a CSS selector from DevTools for a quick result. A quick HTML rule is useful when the element traits look stable but you want control over which attributes are used. If the traits are unstable or random-looking, or the page has many similar blocks, use StableHTMLFinder or the rule builder.

CSS selector reference Back to top

What are selectors?

Selectors find an element on a web page by its properties: tag, class, identifier, attributes, or position in the HTML structure.

In CSS styles, selectors apply formatting. In BlockIt, selectors are used only for finding elements. We do not set colors, fonts, or spacing—we simply find an element in order to block it.

These examples will help you read and make small edits to ordinary CSS selectors.

How to check a selector

1. Open the Elements tab in DevTools.
2. Press Ctrl + F, or Cmd + F on a Mac.
3. Paste the selector into the search field.
4. DevTools highlights all matches and shows their count, for example 1 of 3.

1

Selector types

Standard CSS selectors have limitations. They cannot describe an attribute or class count without listing them, an element’s own text, arbitrary text inside it, regular expressions, or attribute-name patterns. For example, [data-*] is not a standard CSS selector. BlockIt rules are used for these cases: they extend standard CSS syntax with constructs such as [data-*], :attr-name(/^data-/), and other conditions. Read the BlockIt syntax documentation.

<main>
  <h1>Main page</h1>
  <iframe src="advertisement.html"></iframe>
</main>

<video-player>
  #shadow-root (open)
    <button class="play">Play</button>
</video-player>

Managing rules Back to top

Created rules appear in the list for the current site or in the list of rules not tied to a domain. Rules made in the builder can be edited or deleted; disabled rules remain in the list with a corresponding label.

Disabling and deleting

How do I disable a rule?

Find the rule in “Active rules” and click “Disable.” The rule stays in place with a “Disabled” label but is no longer applied. If it has already removed an element from the open page, refresh the page to restore its original content.

How do I delete a rule?

Find the rule in “Active rules” and click “Delete.” To restore an element already removed from the open page, reload it with F5 or the tab’s refresh button.

Export and import

Export saves rules to a file. Import adds rules from such a file or replaces the current list with them. Use this feature to transfer settings and share them between devices.

‹

›

1

Checking rules

Open the page where you want to check the rules, then open BlockIt. In the “For this site: <domain>” group heading, click “Check rules.”

The check shows whether saved rules find elements on the open page. You can take one measurement or enable “Check stability” and choose several reloads. During measurement, BlockIt temporarily stops applying rules, reloads the page, and shows each rule’s match count on every load.

• Works: the rule finds the same non-zero number of elements in every check.
• Unstable: the rule finds elements, but their number changes between loads.
• Did not work: no matches were found on the tested page.
• Error: the rule could not be executed.

The check includes rules for the current base domain and rules not tied to a domain. BlockIt does not separate subdomains when saving a normal domain binding: for example, a rule created on e.mail.ru is stored for mail.ru. However, elements are checked on the exact page from which you opened diagnostics. A working rule for one subdomain or site section may therefore receive “Did not work” on another subdomain or URL. For a reliable result, open the page for which the rule was created and start the check there.