chrome.fontSettings
- Description
Use the
chrome.fontSettings
API to manage Chrome's font settings. - Permissions
fontSettings
Manifest
To use the Font Settings API, you must declare the "fontSettings" permission in the extension manifest. For example:
{
"name": "My Font Settings Extension",
"description": "Customize your fonts",
"version": "0.2",
"permissions": [
"fontSettings"
],
...
}
Generic Font Families and Scripts
Chrome allows for some font settings to depend on certain generic font families and language scripts. For example, the font used for sans-serif Simplified Chinese may be different than the font used for serif Japanese.
The generic font families supported by Chrome are based on CSS generic font families and are listed in the API reference below. When a webpage specifies a generic font family, Chrome selects the font based on the corresponding setting. If no generic font family is specified, Chrome uses the setting for the "standard" generic font family.
When a webpage specifies a language, Chrome selects the font based on the setting for the corresponding language script. If no language is specified, Chrome uses the setting for the default, or global, script.
The supported language scripts are specified by ISO 15924 script code and listed in the API reference below. Technically, Chrome settings are not strictly per-script but also depend on language. For example, Chrome chooses the font for Cyrillic (ISO 15924 script code "Cyrl") when a webpage specifies the Russian language, and uses this font not just for Cyrillic script but for everything the font covers, such as Latin.
Examples
The following code gets the standard font for Arabic.
chrome.fontSettings.getFont(
{ genericFamily: 'standard', script: 'Arab' },
function(details) { console.log(details.fontId); }
);
The next snippet sets the sans-serif font for Japanese.
chrome.fontSettings.setFont(
{ genericFamily: 'sansserif', script: 'Jpan', fontId: 'MS PGothic' }
);
You can find a sample extension using the Font Settings API in the examples/api/fontSettings directory. For other examples and for help in viewing the source code, see Samples.
Summary
- Types
- Methods
- Events
Types
FontName
Represents a font name.
Properties
- displayName
string
The display name of the font.
- fontId
string
The font ID.
GenericFamily
A CSS generic font family.
Type
"standard"
,"sansserif"
,"serif"
,"fixed"
,"cursive"
,"fantasy"
, or"math"
LevelOfControl
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
Type
"not_controllable"
,"controlled_by_other_extensions"
,"controllable_by_this_extension"
, or"controlled_by_this_extension"
ScriptCode
An ISO 15924 script code. The default, or global, script is represented by script code "Zyyy".
Type
"Afak"
,"Arab"
,"Armi"
,"Armn"
,"Avst"
,"Bali"
,"Bamu"
,"Bass"
,"Batk"
,"Beng"
,"Blis"
,"Bopo"
,"Brah"
,"Brai"
,"Bugi"
,"Buhd"
,"Cakm"
,"Cans"
,"Cari"
,"Cham"
,"Cher"
,"Cirt"
,"Copt"
,"Cprt"
,"Cyrl"
,"Cyrs"
,"Deva"
,"Dsrt"
,"Dupl"
,"Egyd"
,"Egyh"
,"Egyp"
,"Elba"
,"Ethi"
,"Geor"
,"Geok"
,"Glag"
,"Goth"
,"Gran"
,"Grek"
,"Gujr"
,"Guru"
,"Hang"
,"Hani"
,"Hano"
,"Hans"
,"Hant"
,"Hebr"
,"Hluw"
,"Hmng"
,"Hung"
,"Inds"
,"Ital"
,"Java"
,"Jpan"
,"Jurc"
,"Kali"
,"Khar"
,"Khmr"
,"Khoj"
,"Knda"
,"Kpel"
,"Kthi"
,"Lana"
,"Laoo"
,"Latf"
,"Latg"
,"Latn"
,"Lepc"
,"Limb"
,"Lina"
,"Linb"
,"Lisu"
,"Loma"
,"Lyci"
,"Lydi"
,"Mand"
,"Mani"
,"Maya"
,"Mend"
,"Merc"
,"Mero"
,"Mlym"
,"Moon"
,"Mong"
,"Mroo"
,"Mtei"
,"Mymr"
,"Narb"
,"Nbat"
,"Nkgb"
,"Nkoo"
,"Nshu"
,"Ogam"
,"Olck"
,"Orkh"
,"Orya"
,"Osma"
,"Palm"
,"Perm"
,"Phag"
,"Phli"
,"Phlp"
,"Phlv"
,"Phnx"
,"Plrd"
,"Prti"
,"Rjng"
,"Roro"
,"Runr"
,"Samr"
,"Sara"
,"Sarb"
,"Saur"
,"Sgnw"
,"Shaw"
,"Shrd"
,"Sind"
,"Sinh"
,"Sora"
,"Sund"
,"Sylo"
,"Syrc"
,"Syre"
,"Syrj"
,"Syrn"
,"Tagb"
,"Takr"
,"Tale"
,"Talu"
,"Taml"
,"Tang"
,"Tavt"
,"Telu"
,"Teng"
,"Tfng"
,"Tglg"
,"Thaa"
,"Thai"
,"Tibt"
,"Tirh"
,"Ugar"
,"Vaii"
,"Visp"
,"Wara"
,"Wole"
,"Xpeo"
,"Xsux"
,"Yiii"
,"Zmth"
,"Zsym"
, or"Zyyy"
Methods
clearDefaultFixedFontSize
chrome.fontSettings.clearDefaultFixedFontSize(
details?:
object,
callback?:
function,
)
Clears the default fixed font size set by this extension, if any.
Parameters
- details
object optional
This parameter is currently unused.
- callback
function optional
The
callback
parameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
clearDefaultFontSize
chrome.fontSettings.clearDefaultFontSize(
details?:
object,
callback?:
function,
)
Clears the default font size set by this extension, if any.
Parameters
- details
object optional
This parameter is currently unused.
- callback
function optional
The
callback
parameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
clearFont
chrome.fontSettings.clearFont(
details:
object,
callback?:
function,
)
Clears the font set by this extension, if any.
Parameters
- details
object
- genericFamily
The generic font family for which the font should be cleared.
- script
ScriptCode optional
The script for which the font should be cleared. If omitted, the global script font setting is cleared.
- callback
function optional
The
callback
parameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
clearMinimumFontSize
chrome.fontSettings.clearMinimumFontSize(
details?:
object,
callback?:
function,
)
Clears the minimum font size set by this extension, if any.
Parameters
- details
object optional
This parameter is currently unused.
- callback
function optional
The
callback
parameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getDefaultFixedFontSize
chrome.fontSettings.getDefaultFixedFontSize(
details?:
object,
callback?:
function,
)
Gets the default size for fixed width fonts.
Parameters
- details
object optional
This parameter is currently unused.
- callback
function optional
The
callback
parameter looks like:(details: object) => void
- details
object
- levelOfControl
The level of control this extension has over the setting.
- pixelSize
number
The font size in pixels.
Returns
Promise<object>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getDefaultFontSize
chrome.fontSettings.getDefaultFontSize(
details?:
object,
callback?:
function,
)
Gets the default font size.
Parameters
- details
object optional
This parameter is currently unused.
- callback
function optional
The
callback
parameter looks like:(details: object) => void
- details
object
- levelOfControl
The level of control this extension has over the setting.
- pixelSize
number
The font size in pixels.
Returns
Promise<object>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getFont
chrome.fontSettings.getFont(
details:
object,
callback?:
function,
)
Gets the font for a given script and generic font family.
Parameters
- details
object
- genericFamily
The generic font family for which the font should be retrieved.
- script
ScriptCode optional
The script for which the font should be retrieved. If omitted, the font setting for the global script (script code "Zyyy") is retrieved.
- callback
function optional
The
callback
parameter looks like:(details: object) => void
- details
object
- fontId
string
The font ID. Rather than the literal font ID preference value, this may be the ID of the font that the system resolves the preference value to. So,
fontId
can differ from the font passed tosetFont
, if, for example, the font is not available on the system. The empty string signifies fallback to the global script font setting. - levelOfControl
The level of control this extension has over the setting.
Returns
Promise<object>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getFontList
chrome.fontSettings.getFontList(
callback?:
function,
)
Gets a list of fonts on the system.
Parameters
Returns
Promise<FontName[]>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getMinimumFontSize
chrome.fontSettings.getMinimumFontSize(
details?:
object,
callback?:
function,
)
Gets the minimum font size.
Parameters
- details
object optional
This parameter is currently unused.
- callback
function optional
The
callback
parameter looks like:(details: object) => void
- details
object
- levelOfControl
The level of control this extension has over the setting.
- pixelSize
number
The font size in pixels.
Returns
Promise<object>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setDefaultFixedFontSize
chrome.fontSettings.setDefaultFixedFontSize(
details:
object,
callback?:
function,
)
Sets the default size for fixed width fonts.
Parameters
- details
object
- pixelSize
number
The font size in pixels.
- callback
function optional
The
callback
parameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setDefaultFontSize
chrome.fontSettings.setDefaultFontSize(
details:
object,
callback?:
function,
)
Sets the default font size.
Parameters
- details
object
- pixelSize
number
The font size in pixels.
- callback
function optional
The
callback
parameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setFont
chrome.fontSettings.setFont(
details:
object,
callback?:
function,
)
Sets the font for a given script and generic font family.
Parameters
- details
object
- fontId
string
The font ID. The empty string means to fallback to the global script font setting.
- genericFamily
The generic font family for which the font should be set.
- script
ScriptCode optional
The script code which the font should be set. If omitted, the font setting for the global script (script code "Zyyy") is set.
- callback
function optional
The
callback
parameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setMinimumFontSize
chrome.fontSettings.setMinimumFontSize(
details:
object,
callback?:
function,
)
Sets the minimum font size.
Parameters
- details
object
- pixelSize
number
The font size in pixels.
- callback
function optional
The
callback
parameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
Events
onDefaultFixedFontSizeChanged
chrome.fontSettings.onDefaultFixedFontSizeChanged.addListener(
callback:
function,
)
Fired when the default fixed font size setting changes.
Parameters
- callback
function
The
callback
parameter looks like:(details: object) => void
- details
object
- levelOfControl
The level of control this extension has over the setting.
- pixelSize
number
The font size in pixels.
onDefaultFontSizeChanged
chrome.fontSettings.onDefaultFontSizeChanged.addListener(
callback:
function,
)
Fired when the default font size setting changes.
Parameters
- callback
function
The
callback
parameter looks like:(details: object) => void
- details
object
- levelOfControl
The level of control this extension has over the setting.
- pixelSize
number
The font size in pixels.
onFontChanged
chrome.fontSettings.onFontChanged.addListener(
callback:
function,
)
Fired when a font setting changes.
Parameters
- callback
function
The
callback
parameter looks like:(details: object) => void
- details
object
- fontId
string
The font ID. See the description in
getFont
. - genericFamily
The generic font family for which the font setting has changed.
- levelOfControl
The level of control this extension has over the setting.
- script
ScriptCode optional
The script code for which the font setting has changed.
onMinimumFontSizeChanged
chrome.fontSettings.onMinimumFontSizeChanged.addListener(
callback:
function,
)
Fired when the minimum font size setting changes.
Parameters
- callback
function
The
callback
parameter looks like:(details: object) => void
- details
object
- levelOfControl
The level of control this extension has over the setting.
- pixelSize
number
The font size in pixels.