From e8d2ea721636e7bd988dcf2b182735f87525e2aa Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Mon, 29 Jun 2026 05:39:21 +1200 Subject: [PATCH] Issue 44584 Clarify filtering comments in background scripts page --- .../add-ons/webextensions/background_scripts/index.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/background_scripts/index.md b/files/en-us/mozilla/add-ons/webextensions/background_scripts/index.md index b69d95d63ecf278..38da84e62aa208d 100644 --- a/files/en-us/mozilla/add-ons/webextensions/background_scripts/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/background_scripts/index.md @@ -164,7 +164,9 @@ browser.runtime.onMessage.addListener( ### Filter events -Use APIs that support event filters to restrict listeners to the cases the extension cares about. If an extension is listening for {{WebExtAPIRef("tabs.onUpdated")}}, use the {{WebExtAPIRef("webNavigation.onCompleted")}} event with filters instead, as the tabs API does not support filters. +When your extension only needs to act on a subset of events, such as when a web page is opened from a specific domain, use event filters where they are available. + +For example, you can add a filter to the {{WebExtAPIRef("webNavigation.onCompleted")}} event to start your background script when certain URLs load, like this: ```js browser.webNavigation.onCompleted.addListener( @@ -175,6 +177,8 @@ browser.webNavigation.onCompleted.addListener( ); ``` +When targeting Firefox desktop only, you can also add filters to {{WebExtAPIRef("tabs.onUpdated")}} to achieve a similar outcome. + ### React to listeners Listeners exist to trigger functionality once an event has fired. To react to an event, structure the desired reaction inside the listener event.