User.js file: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
(change links)
(→‎External links: updated links, reordered; added link to Bug 557738 - Add user.js section to about:support)
 
(47 intermediate revisions by 14 users not shown)
Line 1: Line 1:
: ''This article also serves as a reference for the Firefox counterparts of user.js and prefs.js. It also applies to Thunderbird, except where noted.''
{{profile-file|filename=user.js}}
'''user.js''' is a file that contains preferences that will be loaded into the Mozilla Application Suite every time the suite is started up.  Each time Mozilla is started up, the valid preferences from user.js are copied into prefs.js, which Mozilla uses to store all the preferences for the current user.


The user.js file is located in your [[Profile Folder | profile directory]], the same directory as prefs.js, but it is '''not''' created by Mozilla. So if the file doesn't exist, simply create a new text file with any text editor, such as notepad, emacs, or vi, and save it with the name "user.js".  Make sure you save the file in the same directory as prefs.js.
A ''user.js'' file is an alternative method of [[Editing_configuration#Modifying_preferences |modifying preferences]], recommended for advanced users only.  Unless you need a user.js file for a specific purpose you should use [[about:config]] instead.  The user.js file does not exist by default.  


Mozilla will '''never''' modify the contents of user.js.  However, the contents of prefs.js is frequently modified by Mozilla.  If you wish do modify prefs.js directly, you should take care to shut down Mozilla completely before you open the file. Otherwise your edits may be overwritten.
'''Important: ''' 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 Mozilla application because the user.js entry will override it.


Similar to the user.js file, entering [[about:config]] in the URL bar will allow you to edit the preferences for the current Mozilla user profileChanges made in this manner will directly modify the prefs.js file. (''Does not apply to Thunderbird.'')
==About the user.js file==
A user.js file can make certain preference settings more or less "permanent" in a specific profile, since you'll have to first delete or edit the user.js file to remove the entries before the preferences can be changed in the applicationThis has the advantage of locking in certain preference settings.  A user.js file is also a way of documenting preference customizations and it makes it easier to transfer customized settings to another profile.


To undo preferences that you set using the user.js file, you cannot simply delete the preferences that you inserted previously into user.js, as these will remain written in prefs.js. You should instead delete the preferences from prefs.js by editing that file with a text editor or via about:config.
When you launch your Mozilla application, valid preferences you've added to the user.js file are automatically copied to the [[prefs.js file]] (located in the same [[profile folder]]) where all user-set preferences are stored. For this reason, you should make a backup copy of the prefs.js file before you create or edit the user.js file.  


Valid preferences are via the user_pref command, as demonstrated below.  
==Creating the user.js file==
To create a user.js file, open a text editor such as Notepad and save the empty file as "user.js" inside your [[profile folder]]. (If you use a Windows text editor, make sure you unhide extensions for known filetypes in Folder Options, so that the file isn't really called "user.js.txt". See also the [[Editing configuration/Manual editing | manual editing advice]].)


'''//''' denotes a comment. Anything after these two characters on a line are ignored.
==Adding user.js entries==
To add preferences to user.js, open the file in a text editor such as Notepad, and type in the preference entries (and any comments) as follows. (After adding the entries, you must save the file! Changes will not take effect until you restart your Mozilla application.)


Following are a number of preferences and what they doFor lack of a better way of ordering them, they are alphabetical via preference name. These can be copied "as-is" into your user.js file. (''These browser-specific examples do not apply to Thunderbird.'')
Valid preferences are entered via the user_pref command, as demonstrated below<code>//</code> denotes a comment, so anything after these two characters on a line is ignored.  A valid preference entry always begins with ''user_pref'' and always ends with a semi-colon; every preference must be entered on a new line. A preference consists of a &lsquo;name&rsquo; (such as '''browser.chrome.site_icons''') and a &lsquo;value&rsquo;. A value may either be integer ('''0''', '''2''' etc.), boolean ('''true''' or '''false''') or string (text, such as a file path).  For example, you could add the following lines to your user.js file if you wished to disable bookmark icons:


  // Type-Ahead-Find allows the user to search for text or links on a site by just
  // Don't show bookmark icons
  // typing the search term.
  user_pref("browser.chrome.site_icons", false);


// Find next instance of the search term is <F3>.
Many Knowledge Base articles discuss individual preferences and their values. For a comprehensive list of valid preferences and their values, consult the [[about:config entries]] article.
// Find previous instance of the search term is <Shift-F3>.


// Turn on Type-Ahead-Find
Note that in Windows, if the preference value is a folder path then the path separator must be two backslashes. For example,
// Default: true
user_pref("accessibility.typeaheadfind", true);


  // Allow type-ahead-find to work on text as well as links by default
  // Relocate parent directory for browser cache
// Default: true (Type-Ahead-Find will only work on links)
  user_pref("browser.cache.disk.parent_directory", "D:\\Mozilla\\Firefox\\");
  user_pref("accessibility.typeaheadfind.linksonly", false);


// Block new windows from opening up.
==Editing user.js entries ==
  // Default: false (Allow popups)
To edit the user.js file, open the file in a text editor such as Notepad, make your changes, then close the file and save the changes. Note that removing or "commenting out" a preference line from the user.js file will not remove changes written to the [[prefs.js file]] (see below).
user_pref("browser.block.target_new_window", true);


// IE Favorites (bookmarks) are imported the first time Mozilla is run.
==Removing user.js entries==
// This preference is to determine whether they are shown in the bookmarks menu
To undo preferences that have been set in the user.js file:
  // Default: true (Show IE Favorites under bookmarks)
# Edit the user.js file to remove the unwanted preference entries or delete the user.js file to remove all entries, as a first step.  Since the same preferences are now written to the  [[prefs.js file]], a second step is needed:
  user_pref("browser.bookmarks.import_system_favorites", false);
# If there are no options in the user interface (UI) for the preference, either directly edit the prefs.js file to remove the unwanted entries (not recommended), reset the preference via [[about:config]] or restore a backup copy of the [[prefs.js file]].


// Site icons are icons that show up in the URL bar when visiting a site.
==See also==
// Favicons are a broken implementation of site icons used by Internet Explorer.
*[[Resetting preferences]]
// Web pages are supposed to tell us if they have a site icon. 
*[[Editing configuration]]
// Since IE looks for favicons on *all* sites, this causes unnecessary page hits.
// Mozilla can do the same by setting the following preference.
// Default: false (Don't look for favicons unless they're
// explicitly specified in the web page.)
user_pref("browser.chrome.favicons", true);


// Look for site icons if site specifies them
==External links==
// Default: true (Load site icons if they are specified in the web page)
* [http://ilias.ca/archive/userjs How to Create and Use the user.js in Windows] (ilias.ca)
user_pref("browser.chrome.site_icons", true);
* [http://webdesigns.ms11.net/chromeditp.html ChromEdit Plus] This extension provides a convenient way of editing user.js and other Mozilla configuration files
// 0 - No
* [https://developer.mozilla.org/en-US/docs/Code_snippets/Preferences Preferences - MDN]
// 1 - Show icons only if they're cached
* [https://developer.mozilla.org/en-US/docs/Thunderbird/Thunderbird_Configuration_Files Thunderbird Configuration Files - MDN]
// 2 - Always show icons
* [http://www-archive.mozilla.org/catalog/end-user/customizing/briefprefs.html A Brief Guide to Mozilla Preferences]
// Default: 0
* [https://bugzilla.mozilla.org/show_bug.cgi?id=557738 Bug 557738 - Add user.js section to about:support]
user_pref("browser.chrome.load_toolbar_icons", 2);


// Allow images that are too big to be resized.
// Image resizing is used if a image is viewed that's too large to fit in the browser
// window.
// Default: false
user_pref("browser.enable_automatic_image_resizing", true);


// When opening a link in a new tab, the default behavior is to
[[Category:Configuration]]
// put focus on the new tab.
[[Category:Configuration (Thunderbird)]]
// Default: false (Focus always goes to the newly created tab)
user_pref("browser.tabs.loadInBackground", true);
// Open a link in a new tab if you 'middle click' on the link. Clicking down on a
//    mouse wheel is concidered a middle click.
// Default: false (Middle click will open the link in a new browser window)
user_pref("browser.tabs.opentabfor.middleclick", true);
 
// If multiple tabs are open and you close the window, the default behaviour is
// to warn you that there are open tabs.
// Default: true (Warn if closing the browser window will close multiple tabs)
user_pref("browser.tabs.warnOnClose", false);
 
// The browser window has a throbber. By default, all throbbers will take the
//    browser window to www.mozilla.org, but this is easy to change.
// Default: "http://www.mozilla.org/"
user_pref("browser.throbber.url", "http://www.yahoo.com/");
 
 
// Automatically complete text typed into location bar.
// Default: true (Browser will try to autocomplete what the user types into the
// location bar)
user_pref("browser.urlbar.autocomplete.enabled", true);
 
// Show a dropdown list of possible matches for what the user has typed in.
// Default: true
user_pref("browser.urlbar.showPopup", true);
 
// Enable smooth scroll on PgUP/PgDn, similar to IE.
// Default: false
user_pref("general.smoothScroll", true);
 
===External Links===
* [[About:config Entries]] for Firefox - A collection of descriptions for every [[about:config]] (prefs.js) entry. Still in its early roots. Most should apply to Mozilla too.
* [http://www.geocities.com/pratiksolanki/ Hidden Mozilla Prefs]
* [http://www.mozilla.org/support/firefox/tips Firefox Help: Tips and Tricks] - Most should also apply to Mozilla
* [http://texturizer.net/thunderbird/tips.html Thunderbird Help: Tips and Tricks] has a number of tweaks you can make by modifying user.js in your Thunderbird profile.

Latest revision as of 15:17, 11 October 2012

A user.js file is an alternative method of modifying preferences, recommended for advanced users only. Unless you need a user.js file for a specific purpose you should use about:config instead. The user.js file does not exist by default.

Important: 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 Mozilla application because the user.js entry will override it.

About the user.js file

A user.js file can make certain preference settings more or less "permanent" in a specific profile, since 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. This has the advantage of locking in certain preference settings. A user.js file is also a way of documenting preference customizations and it makes it easier to transfer customized settings to another profile.

When you launch your Mozilla application, valid preferences you've added to the user.js file are automatically copied to the prefs.js file (located in the same profile folder) where all user-set preferences are stored. For this reason, you should make a backup copy of the prefs.js file before you create or edit the user.js file.

Creating the user.js file

To create a user.js file, open a text editor such as Notepad and save the empty file as "user.js" inside your profile folder. (If you use a Windows text editor, make sure you unhide extensions for known filetypes in Folder Options, so that the file isn't really called "user.js.txt". See also the manual editing advice.)

Adding user.js entries

To add preferences to user.js, open the file in a text editor such as Notepad, and type in the preference entries (and any comments) as follows. (After adding the entries, you must save the file! Changes will not take effect until you restart your Mozilla application.)

Valid preferences are entered via the user_pref command, as demonstrated below. // denotes a comment, so anything after these two characters on a line is ignored. A valid preference entry always begins with user_pref and always ends with a semi-colon; every preference must be entered on a new line. A preference consists of a ‘name’ (such as browser.chrome.site_icons) and a ‘value’. A value may either be integer (0, 2 etc.), boolean (true or false) or string (text, such as a file path). For example, you could add the following lines to your user.js file if you wished to disable bookmark icons:

// Don't show bookmark icons
user_pref("browser.chrome.site_icons", false);

Many Knowledge Base articles discuss individual preferences and their values. For a comprehensive list of valid preferences and their values, consult the about:config entries article.

Note that in Windows, if the preference value is a folder path then the path separator must be two backslashes. For example,

// Relocate parent directory for browser cache
user_pref("browser.cache.disk.parent_directory", "D:\\Mozilla\\Firefox\\");

Editing user.js entries

To edit the user.js file, open the file in a text editor such as Notepad, make your changes, then close the file and save the changes. Note that removing or "commenting out" a preference line from the user.js file will not remove changes written to the prefs.js file (see below).

Removing user.js entries

To undo preferences that have been set in the user.js file:

  1. Edit the user.js file to remove the unwanted preference entries or delete the user.js file to remove all entries, as a first step. Since the same preferences are now written to the prefs.js file, a second step is needed:
  2. If there are no options in the user interface (UI) for the preference, either directly edit the prefs.js file to remove the unwanted entries (not recommended), reset the preference via about:config or restore a backup copy of the prefs.js file.

See also

External links