chrome.types

Description

Thechrome.types API contains type declarations for Chrome.

Chrome settings

TheChromeSetting type provides a common set of functions (get(),set(), andclear())as well as an event publisher (onChange) for settings of the Chrome browser. Theproxy settingsexamples demonstrate how these functions are intended to be used.

Scope and lifecycle

Chrome distinguishes between three different scopes of browser settings:

regular
Settings set in theregular scope apply to regular browser windows and are inherited by incognitowindows if they are not overwritten. These settings are stored to disk and remain in place untilthey are cleared by the governing extension, or the governing extension is disabled or uninstalled.
incognito_persistent
Settings set in theincognito_persistent scope apply only to incognito windows. For these, theyoverrideregular settings. These settings are stored to disk and remain in place until they arecleared by the governing extension, or the governing extension is disabled or uninstalled.
incognito_session_only
Settings set in theincognito_session_only scope apply only to incognito windows. For these, theyoverrideregular andincognito_persistent settings. These settings are not stored to disk andare cleared when the last incognito window is closed. They can only be set when at least oneincognito window is open.

Precedence

Chrome manages settings on different layers. The following list describes the layers that mayinfluence the effective settings, in increasing order of precedence.

  1. System settings provided by the operating system
  2. Command-line parameters
  3. Settings provided by extensions
  4. Policies

As the list implies, policies might overrule any changes that you specify with your extension. Youcan use theget() function to determine whether your extension is capable of providing a settingor whether this setting would be overridden.

As discussed previously, Chrome allows using different settings for regular windows and incognitowindows. The following example illustrates the behavior. Assume that no policy overrides thesettings and that an extension can set settings for regular windows(R) and settings forincognito windows(I).

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

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

Theeffective value of a setting is the one that results from considering the precedence rules. Itis used by Chrome.

Types

ChromeSetting

An interface that allows access to a Chrome browser setting. SeeaccessibilityFeatures for an example.

Properties

  • onChange

    Event<functionvoidvoid>

    Fired after the setting changes.

    TheonChange.addListener function looks like:

    (callback: function) => {...}

    • callback

      function

      Thecallback parameter looks like:

      (details: object) => void

      • details

        object

        • incognitoSpecific

          boolean optional

          Whether the value that has changed is specific to the incognito session.This property willonly be present if the user has enabled the extension in incognito mode.

        • levelOfControl

          The level of control of the setting.

        • value

          T

          The value of the setting after the change.

  • clear

    void

    Clears the setting, restoring any default value.

    Theclear function looks like:

    (details: object) => {...}

    • details

      object

      Which setting to clear.

    • returns

      Promise<void>

      Chrome 96+
  • get

    void

    Gets the value of a setting.

    Theget function looks like:

    (details: object) => {...}

    • details

      object

      Which setting to consider.

      • incognito

        boolean optional

        Whether to return the value that applies to the incognito session (default false).

    • returns

      Promise<object>

      Chrome 96+
  • set

    void

    Sets the value of a setting.

    Theset function looks like:

    (details: object) => {...}

    • details

      object

      Which setting to change.

      • scope

        Where to set the setting (default: regular).

      • value

        T

        The value of the setting.Note that every setting has a specific value type, which is described together with the setting. An extension shouldnot set a value of a different type.

    • returns

      Promise<void>

      Chrome 96+

ChromeSettingScope

Chrome 44+

The scope of the ChromeSetting. One of

  • regular: setting for the regular profile (which is inherited by the incognito profile if not overridden elsewhere),
  • regular\_only: setting for the regular profile only (not inherited by the incognito profile),
  • incognito\_persistent: setting for the incognito profile that survives browser restarts (overrides regular preferences),
  • incognito\_session\_only: setting for the 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).

Enum

"regular"

"regular_only"

"incognito_persistent"

"incognito_session_only"

LevelOfControl

Chrome 44+

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

Enum

"not_controllable"

"controlled_by_other_extensions"

"controllable_by_this_extension"

"controlled_by_this_extension"

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-08-11 UTC.