How to Use Urlwatch with a Custom CSS Selector

To monitor only part of a webpage with urlwatch, add a css filter to the job’s YAML configuration and set it to your CSS selector. For example:

url: https://example.net/css.html
filter:
  - css: ul#groceries > li.unchecked

This selects matching unchecked list items that are direct children of a ul with the ID groceries. urlwatch filters the fetched page content before comparing it, so the selected content becomes the input to change detection. See the urlwatch filter documentation for the documented syntax and limitations.

1. Configure a urlwatch job

First identify the page and the specific content whose changes should trigger a notification. Add a job with its URL and a filter list containing a css entry:

url: https://example.net/css.html
filter:
  - css: ul#groceries > li.unchecked

Use the selector that matches the page’s actual markup. For example, main article .price targets elements with class price inside an article inside main; that is only an example, so inspect the target page before adopting it.

The filter selects matching elements from the content urlwatch obtained. It does not make content appear if that content was absent from the fetched page.

2. Preview the selected content

Run urlwatch’s filter test command and inspect the result before relying on notifications:

urlwatch --test-filter

The preview helps confirm both that the selector matches the intended content and that the output of any later filters is suitable for comparison. If you chain filters, remember that each filter operates on the preceding filter’s output; order therefore matters. The handbook documents filter testing and chaining in its command and filter guidance.

3. Refine the selector and filter chain

CSS is a concise choice when the relevant content is naturally described by page structure, tags, IDs, and classes. urlwatch also documents XPath and simpler element selection approaches. Use the approach that describes the target reliably, then inspect the filtered output.

Selector support has limitations and extensions documented by cssselect. A selector accepted by a browser is not necessarily supported by the installed urlwatch dependency. Check the cssselect documentation for the version in your environment when a selector fails.

For XML content, versioned urlwatch documentation describes configuring CSS selection with method: xml. Namespace handling and selector compatibility depend on the input and installed version, so validate the output with the filter test command. Some filter suboptions described in handbook or older versioned documentation can differ across releases; verify an option such as sorting, skipping, or limiting matches against your installed version before depending on it.

4. Handle JavaScript-rendered pages

A CSS filter can select only from the page content urlwatch has obtained. If the desired element is inserted by JavaScript and is missing from that content, the selector alone cannot find it. The handbook describes browser-based navigate support for pages that need browser rendering. Configure browser navigation where appropriate, then use urlwatch --test-filter to confirm that the rendered content reaches the filter pipeline.

Common problems and fixes

Symptom	Likely cause	What to do
No content appears in the filter preview	The selector does not match the fetched markup, or the desired content is not present in it.	Inspect the page structure and fetched content, correct the selector, and rerun urlwatch --test-filter. For JavaScript-rendered content, consider browser navigation.
Too much content is monitored	The selector matches multiple elements or a broad container.	Narrow it with the actual page’s tag, ID, class, and relationship structure; preview the result again.
A browser accepts the selector, but urlwatch does not	urlwatch’s CSS selection support has limitations and depends on cssselect.	Check the cssselect documentation for the installed dependency version and use a supported selector form.
XML selection behaves unexpectedly	XML mode, namespaces, or selector compatibility may not match the document.	Check the versioned urlwatch documentation for method: xml, account for namespaces, and validate the filtered output.
A chained filter produces unexpected output	A later filter receives the previous filter’s transformed output, and order changes the result.	Review the filter sequence and use the test command to inspect the resulting content.

Reliability and maintenance

Selectors depend on page structure. A site redesign can change tags, IDs, or classes and cause a previously useful selector to return different or empty content. Keep the selector focused on the content that matters, and inspect the filtered output when a job’s results change unexpectedly. Do not assume a selector is correct solely because it parses: the preview should contain the exact content you intend to monitor.

Command options and filter suboptions can vary by urlwatch release. The available research covers the 2.29 online handbook and 2.26 versioned filter documentation; it does not establish the latest release or the dependency version on a particular installation. Verify version-sensitive behavior against the documentation matching your installed release.

Or skip the browser setup

If your goal is to capture a clean screenshot of a page while working on a monitoring workflow, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF; the request below asks for a screenshot of the example page. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does the CSS filter monitor the whole page?

It monitors the content selected by the configured filter, which is then used in urlwatch’s comparison process.

How can I tell what the selector selected?

Run urlwatch --test-filter and inspect the output.

Can a CSS selector extract content created by JavaScript?

Only if that content is present in the content urlwatch passes to the filter. For pages that require browser rendering, consult the handbook’s browser navigation guidance.

Will every browser CSS selector work?

No assumption is safe: urlwatch notes limitations and extensions through cssselect. Check the documentation for the dependency version you use.