You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
paramName
( optional enumerated Type array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Parameters

Google Chrome Extensions (Labs)

Preferences

Preferences

The chrome.preferences module contains a prototype for giving other modules access to manage preferences stored by Chrome. This prototype is used, for example, for chrome.proxy.settings.

Overview

The preferences API provides a common set of functions (get(), set(), and clear()) as well as an event publisher (onChange) for various preferences in Chrome. The proxy settings examples demonstrate how these functions are intended to be used.

Scope and life cycle of preferences

Chrome distinguishes between three different scopes of preferences:

regular
Preferences set in the regular scope apply to regular browser windows and are inherited by the incognito windows if they are not overwritten. These preferences are stored to disk and remain in place until they are cleared by the governing extension, or the governing extension is disabled or uninstalled.
incognito_persistent
Preferences set in the incognito_persistent scope apply only to incognito windows. For these, they override regular preferences. These preferences are stored to disk and remain in place until they are cleared by the governing extension, or the governing extension is disabled or uninstalled.
incognito_session_only
Preferences set in the incognito_session_only scope apply only to incognito windows. For these, they override regular and incognito_session_only preferences. These preferences are not stored to disk and are cleared when the last incognito window is closed. They can only be set when at least one incognito window is open.

Precedence

Chrome manages preferences on different layers. The following list describes the layers that may influence the effective preferences, in increasing order of precedence.

  1. System preferences provided by the operating system
  2. Command-line parameters
  3. Preferences set by extensions
  4. Policies

As the list implies, policies might overrule any changes that you specify with your extension. You can use the get() function to determine whether your extension is capable of setting a preference or whether this setting would be overridden.

As discussed above, Chrome allows using different preferences for regular windows and incognito windows. The following example illustrates the behavior. Assume that no policy overrides the preferences and that an extension can set preferences for regular windows (R) and preferences for incognito windows (I).

  • If only (R) is set, these preferences are effective for both regular and incognito windows.
  • If only (I) is set, these preferences are effective for only incognito windows. Regular windows use the preferences determined by the lower layers (command-line options and system settings).
  • If both (R) and (I) are set, the respective preferences are used for regular and incognito windows.

If two or more extensions want to set the same preference to different values, the extension installed most recently takes precedence over the other extensions. If the most recently installed extension sets only (I), the preference of regular windows can be defined by previously installed extensions.

The effective preference value is the setting that results from considering the preference rules. It is used by Chrome.

API reference: chrome.preferences

Types

Preference

paramName
( Type array of object )
An object which allows access to a preference.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Methods of Preference

clear

void preference.clear(, object details, function callback)

Clears the setting in the user preferences. This way default settings can become effective again.

Parameters

details
( Type array of object )
What preference to clear.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
scope
( optional enumerated Type array of string ["regular", "incognito_persistent", "incognito_session_only"] )
Where to set the preference (default: regular). One of
regular: preference for regular profile (which is inherited by the incognito profile if not overridden elsewhere),
incognito_persistent: preference for incognito profile that survives browser restarts (overrides regular preferences),
incognito_session_only: preference for incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular and incognito_persistent preferences).
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( optional Type array of function )
Called after the preference has been cleared.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function() {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

get

void preference.get(, object details, function callback)

Get the setting from the user preferences.

Parameters

details
( Type array of object )
What setting to return.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
incognito
( optional Type array of boolean )
Whether to return the setting that applies to the incognito session (default false).
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(object details) {...};
details
( Type array of object )
Details of the currently effective preference value.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
value
( Type array of any )
The value of the preference.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
levelOfControl
( enumerated Type array of string ["not_controllable", "controlled_by_other_extensions", "controllable_by_this_extension", "controlled_by_this_extension"] )
One of
not_controllable: cannot be controlled by any extension
controlled_by_other_extensions: controlled by extensions with higher precedence
controllable_by_this_extension: can be controlled by this extension
controlled_by_this_extension: controlled by this extension
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
incognitoSpecific
( optional Type array of boolean )
Whether the effective value is specific to the incognito session.
This property will only be present if the incognito property in the details parameter of get() was true.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

set

void preference.set(, object details, function callback)

Set the setting in the user preferences

Parameters

details
( Type array of object )
What setting to change.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
value
( Type array of any )
The value of the preference.
Note that every preference has a specific value type, which is described together with the preference. An extension should not set a preference value of a different type.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
scope
( optional enumerated Type array of string ["regular", "incognito_persistent", "incognito_session_only"] )
Where to set the preference (default: regular). One of
regular: preference for regular profile (which is inherited by the incognito profile if not overridden elsewhere),
incognito_persistent: preference for incognito profile that survives browser restarts (overrides regular preferences),
incognito_session_only: preference for incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular and incognito_persistent preferences).
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( optional Type array of function )
Called after the preference has been set.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function() {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Events of Preference

onChange

preference.onChange.addListener(function(object details) {...}));

Fired when the value of the preference changes.

Listener parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
value
( Type array of any )
The value of the preference.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
levelOfControl
( enumerated Type array of string ["not_controllable", "controlled_by_other_extensions", "controllable_by_this_extension", "controlled_by_this_extension"] )
One of
not_controllable: cannot be controlled by any extension
controlled_by_other_extensions: controlled by extensions with higher precedence
controllable_by_this_extension: can be controlled by this extension
controlled_by_this_extension: controlled by this extension
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
incognitoSpecific
( optional Type array of boolean )
Whether the value that has changed is specific to the incognito session.
This property will only be present if the user has enabled the extension in incognito mode.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

Listener returns