browserSettings API

Hint

The browserSettings API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.

Use the browser.browserSettings API to control global settings of the browser.

Permissions

The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.

Hint

Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.

browserSettings



Read and modify browser settings.

Note

The permission browserSettings is required to use messenger.browserSettings.*.

Types

ColorManagementMode

Color management mode.

string

Supported values:

full



off



tagged_only



ContextMenuMouseEvent

After which mouse event context menus should popup.

string

Supported values:

mousedown



mouseup



ImageAnimationBehavior

How images should be animated in the browser.

string

Supported values:

none



normal



once



Settings

write allowPopupsForUserEvents

– [Added in TB 57]

Allows or disallows pop-up windows from opening in response to user events.

write cacheEnabled

– [Added in TB 56]

Enables or disables the browser cache.

write closeTabsByDoubleClick

This boolean setting controls whether the selected tab can be closed with a double click.

write contextMenuShowEvent

– [Added in TB 59]

Controls after which mouse event context menus popup. This setting’s value is of type ContextMenuMouseEvent, which has possible values of mouseup and mousedown.

write ftpProtocolEnabled

– [Added in TB 72]

Returns whether the FTP protocol is enabled. Read-only.

Note

From version 88, this setting is read-only (see bug 1626365).

write homepageOverride

Returns the value of the overridden home page. Read-only.

write imageAnimationBehavior

– [Added in TB 57]

Controls the behaviour of image animation in the browser. This setting’s value is of type ImageAnimationBehavior, defaulting to normal.

write newTabPageOverride

Returns the value of the overridden new tab page. Read-only.

write newTabPosition

Controls where new tabs are opened. afterCurrent will open all new tabs next to the current tab, relatedAfterCurrent will open only related tabs next to the current tab, and atEnd will open all tabs at the end of the tab strip. The default is relatedAfterCurrent.

write openBookmarksInNewTabs

This boolean setting controls whether bookmarks are opened in the current tab or in a new tab.

write openSearchResultsInNewTabs

This boolean setting controls whether search results are opened in the current tab or in a new tab.

write openUrlbarResultsInNewTabs

This boolean setting controls whether urlbar results are opened in the current tab or in a new tab.

write overrideContentColorScheme

– [Added in TB 95]

This setting controls whether a light or dark color scheme overrides the page’s preferred color scheme.

write overrideDocumentColors

– [Added in TB 61]

This setting controls whether the user-chosen colors override the page’s colors.

write useDocumentFonts

– [Added in TB 61]

This setting controls whether the document’s fonts are used.

write verticalTabs

This boolean setting controls whether vertical tabs are enabled.

write webNotificationsDisabled

– [Added in TB 58]

Disables webAPI notifications.

write zoomFullPage

– [Added in TB 75]

This boolean setting controls whether zoom is applied to the full page or to text only.

write zoomSiteSpecific

This boolean setting controls whether zoom is applied on a per-site basis or to the current tab only. If privacy.resistFingerprinting is true, this setting has no effect and zoom is applied to the current tab only.