Add-ons

selection

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to use WebExtensions APIs if they can. See the "Compatibility Milestones" document for more information.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Stable

Get and set text and HTML selections in the current web page.

Usage

Registering for Selection Notifications

To be notified when the user makes a selection, register a listener for the "select" event. Each listener will be called after a selection is made.

function myListener() {
  console.log("A selection has been made.");
}
var selection = require("sdk/selection");
selection.on('select', myListener);

// You can remove listeners too.
selection.removeListener('select', myListener);

Iterating Over Discontiguous Selections

Discontiguous selections can be accessed by iterating over the selection module itself. Each iteration yields a Selection object from which text, html, and isContiguous properties can be accessed.

Private Windows

If your add-on has not opted into private browsing, then you won't see any selections made in tabs that are hosted by private browser windows.

To learn more about private windows, how to opt into private browsing, and how to support private browsing, refer to the documentation for the private-browsing module.

Examples

Log the current contiguous selection as text:

var selection = require("sdk/selection");
if (selection.text)
  console.log(selection.text);

Log the current discontiguous selections as HTML:

var selection = require("sdk/selection");
if (!selection.isContiguous) {
  for (var subselection in selection) {
     console.log(subselection.html);
  }
}

Surround HTML selections with delimiters:

var selection = require("sdk/selection");
selection.on('select', function () {
  selection.html = "\\\" + selection.html + "///";
});

Globals

Properties

text

Gets or sets the current selection as plain text. Setting the selection removes all current selections, inserts the specified text at the location of the first selection, and selects the new text. Getting the selection when there is no current selection returns null. Setting the selection when there is no current selection throws an exception. Getting the selection when isContiguous is true returns the text of the first selection.

html

Gets or sets the current selection as HTML. Setting the selection removes all current selections, inserts the specified text at the location of the first selection, and selects the new text. Getting the selection when there is no current selection returns null. Setting the selection when there is no current selection throws an exception. Getting the selection when isContiguous is true returns the text of the first selection.

isContiguous

true if the current selection is a single, contiguous selection, and false if there are two or more discrete selections, each of which may or may not be spatially adjacent. (Discontiguous selections can be created by the user with Ctrl+click-and-drag.)

Events

select

This event is emitted whenever the user makes a new selection in a page.

Document Tags and Contributors

Tags: 
 Contributors to this page: wbamberg
 Last updated by: wbamberg,