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
FontName
GenericFamily
LevelOfControl
ScriptCode
Methods
clearDefaultFixedFontSize
clearDefaultFixedFontSize(details?: object): Promise<object>
clearDefaultFixedFontSize(details?: object, callback?: function): void
clearDefaultFontSize
clearDefaultFontSize(details?: object): Promise<object>
clearDefaultFontSize(details?: object, callback?: function): void
clearFont
clearFont(details: object): Promise<object>
clearFont(details: object, callback?: function): void
clearMinimumFontSize
clearMinimumFontSize(details?: object): Promise<object>
clearMinimumFontSize(details?: object, callback?: function): void
getDefaultFixedFontSize
getDefaultFixedFontSize(details?: object): Promise<object>
getDefaultFixedFontSize(details?: object, callback?: function): void
getDefaultFontSize
getDefaultFontSize(details?: object): Promise<object>
getDefaultFontSize(details?: object, callback?: function): void
getFont
getFont(details: object): Promise<object>
getFont(details: object, callback?: function): void
getFontList
getFontList(): Promise<object>
getFontList(callback: function): void
getMinimumFontSize
getMinimumFontSize(details?: object): Promise<object>
getMinimumFontSize(details?: object, callback?: function): void
setDefaultFixedFontSize
setDefaultFixedFontSize(details: object): Promise<object>
setDefaultFixedFontSize(details: object, callback?: function): void
setDefaultFontSize
setDefaultFontSize(details: object): Promise<object>
setDefaultFontSize(details: object, callback?: function): void
setFont
setFont(details: object): Promise<object>
setFont(details: object, callback?: function): void
setMinimumFontSize
setMinimumFontSize(details: object): Promise<object>
setMinimumFontSize(details: object, callback?: function): void
Events
onDefaultFixedFontSizeChanged
onDefaultFontSizeChanged
onFontChanged
onMinimumFontSizeChanged

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.

Enum

"standard", "sansserif", "serif", "fixed", "cursive", or "fantasy"

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

Enum

"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".

Enum

"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

clearDefaultFixedFontSize(details?: object): Promise<object>
clearDefaultFixedFontSize(details?: object, callback?: function): void

Promise

Clears the default fixed font size set by this extension, if any.

Parameters

details
object optional
This parameter is currently unused.

Result

return/callback
async
The clearDefaultFixedFontSize method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

clearDefaultFontSize

clearDefaultFontSize(details?: object): Promise<object>
clearDefaultFontSize(details?: object, callback?: function): void

Promise

Clears the default font size set by this extension, if any.

Parameters

details
object optional
This parameter is currently unused.

Result

return/callback
async
The clearDefaultFontSize method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

clearFont

clearFont(details: object): Promise<object>
clearFont(details: object, callback?: function): void

Promise

Clears the font set by this extension, if any.

Parameters

details
object
- genericFamily
  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.

Result

return/callback
async
The clearFont method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

clearMinimumFontSize

clearMinimumFontSize(details?: object): Promise<object>
clearMinimumFontSize(details?: object, callback?: function): void

Promise

Clears the minimum font size set by this extension, if any.

Parameters

details
object optional
This parameter is currently unused.

Result

return/callback
async
The clearMinimumFontSize method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

getDefaultFixedFontSize

getDefaultFixedFontSize(details?: object): Promise<object>
getDefaultFixedFontSize(details?: object, callback?: function): void

Promise

Gets the default size for fixed width fonts.

Parameters

details
object optional
This parameter is currently unused.

Result

return/callback
async
The getDefaultFixedFontSize method provides its result via callback or returned as a Promise (MV3 only).
- details
  object
  - levelOfControl
    LevelOfControl
    The level of control this extension has over the setting.
  - pixelSize
    number
    The font size in pixels.

getDefaultFontSize

getDefaultFontSize(details?: object): Promise<object>
getDefaultFontSize(details?: object, callback?: function): void

Promise

Gets the default font size.

Parameters

details
object optional
This parameter is currently unused.

Result

return/callback
async
The getDefaultFontSize method provides its result via callback or returned as a Promise (MV3 only).
- details
  object
  - levelOfControl
    LevelOfControl
    The level of control this extension has over the setting.
  - pixelSize
    number
    The font size in pixels.

getFont

getFont(details: object): Promise<object>
getFont(details: object, callback?: function): void

Promise

Gets the font for a given script and generic font family.

Parameters

details
object
- genericFamily
  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.

Result

return/callback
async
The getFont method provides its result via callback or returned as a Promise (MV3 only).
- 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 to setFont, if, for example, the font is not available on the system. The empty string signifies fallback to the global script font setting.
  - levelOfControl
    LevelOfControl
    The level of control this extension has over the setting.

getFontList

getFontList(): Promise<object>
getFontList(callback: function): void

Promise

Gets a list of fonts on the system.

Result

return/callback
async
The getFontList method provides its result via callback or returned as a Promise (MV3 only).
- results
  FontName[]

getMinimumFontSize

getMinimumFontSize(details?: object): Promise<object>
getMinimumFontSize(details?: object, callback?: function): void

Promise

Gets the minimum font size.

Parameters

details
object optional
This parameter is currently unused.

Result

return/callback
async
The getMinimumFontSize method provides its result via callback or returned as a Promise (MV3 only).
- details
  object
  - levelOfControl
    LevelOfControl
    The level of control this extension has over the setting.
  - pixelSize
    number
    The font size in pixels.

setDefaultFixedFontSize

setDefaultFixedFontSize(details: object): Promise<object>
setDefaultFixedFontSize(details: object, callback?: function): void

Promise

Sets the default size for fixed width fonts.

Parameters

details
object
- pixelSize
  number
  The font size in pixels.

Result

return/callback
async
The setDefaultFixedFontSize method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

setDefaultFontSize

setDefaultFontSize(details: object): Promise<object>
setDefaultFontSize(details: object, callback?: function): void

Promise

Sets the default font size.

Parameters

details
object
- pixelSize
  number
  The font size in pixels.

Result

return/callback
async
The setDefaultFontSize method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

setFont

setFont(details: object): Promise<object>
setFont(details: object, callback?: function): void

Promise

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
  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.

Result

return/callback
async
The setFont method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

setMinimumFontSize

setMinimumFontSize(details: object): Promise<object>
setMinimumFontSize(details: object, callback?: function): void

Promise

Sets the minimum font size.

Parameters

details
object
- pixelSize
  number
  The font size in pixels.

Result

return/callback
async
The setMinimumFontSize method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

Events

onDefaultFixedFontSizeChanged

onDefaultFixedFontSizeChanged.addListener(listener: function)

Fired when the default fixed font size setting changes.

Event

listener
function
The listener parameter should be a function that looks like this:
(details: object) => {...}
- details
  object
  - levelOfControl
    LevelOfControl
    The level of control this extension has over the setting.
  - pixelSize
    number
    The font size in pixels.

onDefaultFontSizeChanged

onDefaultFontSizeChanged.addListener(listener: function)

Fired when the default font size setting changes.

Event

listener
function
The listener parameter should be a function that looks like this:
(details: object) => {...}
- details
  object
  - levelOfControl
    LevelOfControl
    The level of control this extension has over the setting.
  - pixelSize
    number
    The font size in pixels.

onFontChanged

onFontChanged.addListener(listener: function)

Fired when a font setting changes.

Event

listener
function
The listener parameter should be a function that looks like this:
(details: object) => {...}
- details
  object
  - fontId
    string
    The font ID. See the description in getFont.
  - genericFamily
    GenericFamily
    The generic font family for which the font setting has changed.
  - levelOfControl
    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

onMinimumFontSizeChanged.addListener(listener: function)

Fired when the minimum font size setting changes.

Event

listener
function
The listener parameter should be a function that looks like this:
(details: object) => {...}
- details
  object
  - levelOfControl
    LevelOfControl
    The level of control this extension has over the setting.
  - pixelSize
    number
    The font size in pixels.

chrome.fontSettings

# Manifest

# Generic Font Families and Scripts

# Examples

Summary

Types

FontName

Properties

GenericFamily

Enum

LevelOfControl

Enum

ScriptCode

Enum

Methods

clearDefaultFixedFontSize

Parameters

Result

clearDefaultFontSize

Parameters

Result

clearFont

Parameters

Result

clearMinimumFontSize

Parameters

Result

getDefaultFixedFontSize

Parameters

Result

getDefaultFontSize

Parameters

Result

getFont

Parameters

Result

getFontList

Result

getMinimumFontSize

Parameters

Result

setDefaultFixedFontSize

Parameters

Result

setDefaultFontSize

Parameters

Result

setFont

Parameters

Result

setMinimumFontSize

Parameters

Result

Events

onDefaultFixedFontSizeChanged

Event

onDefaultFontSizeChanged

Event

onFontChanged

Event

onMinimumFontSizeChanged

Event

Manifest

Generic Font Families and Scripts

Examples