index.md

---

title: runtime.onConnect
slug: Mozilla/Add-ons/WebExtensions/API/runtime/onConnect
page-type: webextension-api-event
tags:
  - API
  - Add-ons
  - Event
  - Extensions
  - Non-standard
  - Reference
  - WebExtensions
  - onconnect
  - runtime
browser-compat: webextensions.api.runtime.onConnect

---

{{AddonSidebar()}}

Fired when a connection is made with either an extension process or a content script.

Syntax

browser.runtime.onConnect.addListener(listener)
browser.runtime.onConnect.removeListener(listener)
browser.runtime.onConnect.hasListener(listener)

Events have three functions:

• addListener(callback)

  • : Adds a listener to this event.

• removeListener(listener)

  • : Stop listening to this event. The listener argument is the listener to remove.

• hasListener(listener)

  • : Checks whether a listener is registered for this event. Returns true if it is listening, false otherwise.

addListener syntax

Parameters

• function

  • : A callback function that will be called when this event occurs. The function will be passed the following arguments:

    • port

      • : A {{WebExtAPIRef('runtime.Port')}} object connecting the current script to the other context it is connecting to.

Browser compatibility

{{Compat}}

Examples

This content script:

• connects to the background script, and stores the Port in a variable myPort

• listens for messages on myPort, and logs them

• sends messages to the background script, using myPort, when the user clicks the document

// content-script.js

let myPort = browser.runtime.connect({name:"port-from-cs"});
myPort.postMessage({greeting: "hello from content script"});

myPort.onMessage.addListener((m) => {
  console.log("In content script, received message from background script: ");
  console.log(m.greeting);
});

document.body.addEventListener("click", () => {
  myPort.postMessage({greeting: "they clicked the page!"});
});

The corresponding background script:

• listens for connection attempts from the content script

• when it receives a connection attempt:

  • stores the port in a variable named portFromCS

  • sends the content script a message using the port

  • starts listening to messages received on the port, and logs them

• sends messages to the content script, using portFromCS, when the user clicks the extension's browser action

// background-script.js

let portFromCS;

function connected(p) {
  portFromCS = p;
  portFromCS.postMessage({greeting: "hi there content script!"});
  portFromCS.onMessage.addListener((m) => {
    console.log("In background script, received message from content script")
    console.log(m.greeting);
  });
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(() => {
  portFromCS.postMessage({greeting: "they clicked the button!"});
});

{{WebExtExamples}}

Note: This API is based on Chromium's chrome.runtime API. This documentation is derived from runtime.json in the Chromium code.