9.2 KiB
Preference
Table of Contents
Basics
Related Docs
Key/Value
- Key:
- Pref name
- Type: 8-bit string
- Convention is to use a dotted segmented form (Ex.
browser.cache.disk.enable)
- Value:
- Type: bool, 32-bit ints, 8-bit C string
- When you need an float, use a string. (Ex.
general.smoothScroll.currentVelocityWeighting:"0.25")
Main Purpose
- Feature enable/disable flags (Ex.
xpinstall.signatures.required). - User preferences (Ex. things set from
about:preferences) - Internal application parameters (Ex.
javascript.options.mem.nursery.max_kb). - Application data (Ex.
browser.onboarding.tour.onboarding-tour-addons.completed,services.sync.clients.lastSync). - Things that might need locking in an enterprise installation.
Preference file RFC
Key information on the sets that can be used in the configuration file.
pref(): Set default prefstickyattr: same assticky_pref()lockedattr: cannot change from default.
sticky_pref(): Always logged even if the defaults matchuser_pref(): Set user pref
The following is a method of operating the configuration file parser.
See EBNF(Extended Backus-Naur form) if you want to know about syntax.
<pref-file> = <pref>*
<pref> = <pref-spec> "(" <pref-name> "," <pref-value> <pref-attrs> ")" ";"
<pref-spec> = "user_pref" | "pref" | "sticky_pref" // in default pref files
<pref-spec> = "user_pref" // in user pref files
<pref-name> = <string-literal>
<pref-value> = <string-literal> | "true" | "false" | <int-value>
<int-value> = <sign>? <int-literal>
<sign> = "+" | "-"
<int-literal> = [0-9]+ (and cannot be followed by [A-Za-z_])
<string-literal> =
A single or double-quoted string, with the following escape sequences
allowed: \", \', \\, \n, \r, \xNN, \uNNNN, where \xNN gives a raw byte
value that is copied directly into an 8-bit string value, and \uNNNN
gives a UTF-16 code unit that is converted to UTF-8 before being copied
into an 8-bit string value. \x00 and \u0000 are disallowed because they
would cause C++ code handling such strings to misbehave.
<pref-attrs> = ("," <pref-attr>)* // in default pref files
= <empty> // in user pref files
<pref-attr> = "sticky" | "locked" // default pref files only
Default Config
modules/libpref/init/all.js: all productsbrowser/app/profile/firefox.js: only firefox deskstop
In release builds these are all put into omni.ja.
User Config
Related Docs
- mozillaZine: Editing configuration
- Support Mozilla: How to fix preferences that won't save
- Support Mozilla: Reset Firefox preferences to troubleshoot and fix problems
- UDN: A brief guide to Mozilla preferences
Restrictions
It can be defined using only user_pref().
User pref file syntax is slightly more restrictive than default pref file syntax. In user pref files
user_prefdefinitions are allowed butprefandsticky_prefdefinitions are not, and attributes (such aslocked) are not allowed.
File Path
prefs.js, user.js is located in the profile directory.
about:config
It is written to prefs.js in a way that can be set by the GUI.
prefs.js
Related Docs
Basics It exists in the profile directory, and is used to store settings that are changed from defaults or when users added new settings.
In general, Do NOT edit prefs.js directly.
user.js
Related Docs
Restrictions
A user.js file can make certain preference settings more or less "permanent" in a specific profile.
Once an entry for a preference setting exists in the user.js file, any change you make to that setting in the options and preference dialogs or via about:config will be lost when you restart your firefox because the user.js entry will override it.
You'll have to first delete or edit the user.js file to remove the entries before the preferences can be changed in the application.
Example
// user.js
user_pref("browser.cache.disk.enable", false); // Bool
user_pref("layout.css.prefers-color-scheme.content-override", 3); // Int
user_pref("general.smoothScroll.currentVelocityWeighting", "0.12"); // String
Auto Config
Related Docs
- Support Mozilla: Customizing Firefox Using AutoConfig
- What is Autoconfig Startup Scripting (AKA userChrome.js)?
- UDN: Gecko Chrome
- UDN: JavaScript code modules
- UDN: Limitations of chrome scripts
Basics
Customizations that cannot be done with add-on and User Custom CSS, such as adding browser UI elements directly or changing default behavior, must use Auto Config.
How to
pref("general.config.filename", "config.js"); // alternative to "firefox.cfg", for using highlight
pref("general.config.obscure_value", 0);
Example
pref("general.config.filename", "config.js"); // alternative to "firefox.cfg", for using highlight
pref("general.config.obscure_value", 0);
Using with User Custom CSS
Related Docs
Restrictions
Please refer to Doc: Restrictions.md's @support.
Example
Test each case by turning on/off the following settings.
userChrome.navBar.reduserChrome.navBar.margin
/* userChrome.css */
/* 1. If config is true */
@supports -moz-bool-pref("userChrome.navBar.red") {
#nav-bar {
background-color: red !important;
}
}
/* 2. When any one of the config is true */
@supports -moz-bool-pref("userChrome.navBar.red") or -moz-bool-pref("userChrome.navBar.margin") {
#nav-bar {
background-color: red !important;
margin-block: 20px;
}
}
/* 3. Multiple configs must all be satisfied */
@supports -moz-bool-pref("userChrome.navBar.red") and -moz-bool-pref("userChrome.navBar.margin") {
#nav-bar {
background-color: red !important;
margin-block: 20px;
}
}
/* 4. 3's Other version */
@supports -moz-bool-pref("userChrome.navBar.red") {
@supports -moz-bool-pref("userChrome.navBar.margin") {
#nav-bar {
background-color: red !important;
margin-block: 20px;
}
}
}
/* 5. If not exist or false */
@supports not -moz-bool-pref("userChrome.navBar.red") {
#nav-bar {
background-color: blue !important;
}
}
Sync
Related Docs
How to
Firefox Sync allows you to choose the types of data to sync across all devices.
The following options are required to sync custom configs.
services.sync.prefs.dangerously_allow_arbitrarytotrue
Then, subsequently any pref can be pushed there by creating a remote with prefix.
services.sync.prefs.sync.
Example
// user.js
user_pref("services.sync.prefs.dangerously_allow_arbitrary", true); // Must need
// Sync UI
user_pref("services.sync.prefs.sync.browser.uiCustomization.state", true);
user_pref("services.sync.prefs.sync.browser.uidensity", true);