Archive of obsolete content

preferences/service

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.

Unstable

Access the Preferences system in Firefox. This enables add-ons to get and set system-wide settings. These are the same preferences that are exposed to users in the about:config page.
 
preferences/service gives you full access to the preferences system. You can also use the simple-prefs module to access just the preferences for your own add-on and expose them to the user in the Add-on Manager.

Globals

Functions

set(name, value)

Sets the application preference name to value.

Parameters

name : string
Preference name.

value : string,number,boolean
Preference value.

Example:

var name = "extensions.checkCompatibility.nightly";
require("sdk/preferences/service").set(name, false);

get(name, defaultValue)

Gets the application preference name.

Parameters

name : string

defaultValue : string,number,boolean
Preference value.

Returns

string,number,boolean : Preference value, returns defaultValue if no preference is set, returns undefined if defaultValue is not provided.

Example:

var name = "extensions.checkCompatibility.nightly";
var nightlyCompatChk = require("sdk/preferences/service").get(name);

has(name)

Parameters

name : string
Preference name.

Returns

boolean : Returns whether or not the application preference name exists.

defaultValue

Example:

var name = "extensions.checkCompatibility.nightly";
if (require("sdk/preferences/service").has(name)) {
  // ...
}

keys(root)

Parameters

root : string
Preference root name.

Returns

array : Returns an array of strings representing the child preferences of the root of this branch.

isSet(name)

Parameters

name : string
Preference name.

Returns

boolean : Returns whether or not the application preference name both exists and has been set to a non-default value by the user (or a program acting on the user's behalf).

Example:

var name = "extensions.checkCompatibility.nightly";
if (require("sdk/preferences/service").isSet(name)) {
  // ...
}

reset(name)

Clears a non-default, user-set value from the application preference name. If no user-set value is defined on name, the function does nothing. If no default value exists the preference will cease to exist.

Parameters

name : string
Preference name.

Example:

var name = "extensions.checkCompatibility.nightly";
require("sdk/preferences/service").reset(name);

getLocalized(name, defaultValue)

Gets the localized value for an application preference name.

Parameters

name : string

defaultValue : string
Preference value.

Returns

string : Localized preference value, returns a default value if no preference is set. Some preferences refer to a properties file. So that prefs.get returns the properties file URL whereas prefs.getLocalized returns the value defined in the properties file.

Example:

var prefs = require("sdk/preferences/service");
var name = "general.useragent.locale";
prefs.get(name); // is equal to "chrome://global/locale/intl.properties"
prefs.getLocalized(name) // is equal to "en-US"

setLocalized(name, value)

Sets the localized application preference name to value.

Parameters

name : string
Preference name.

value : string
Preference value, a URL to a properties file

Example:

require("sdk/preferences/service").set("general.useragent.locale",
                                   "chrome://global/locale/intl.properties");

Example: Setting Global Preferences

var { get, set } = require("sdk/preferences/service");
var { when: unload } = require("sdk/system/unload");

var oldValue = get("browser.urlbar.autoFill");
set("browser.urlbar.autoFill", true);

// By AMO policy global preferences must be changed back to their original value
unload(function() {
  set("browser.urlbar.autoFill", oldValue);
});

Document Tags and Contributors

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