: family : style : weight : stretch : unicodeRange :: These attributes all represent the corresponding aspects of a font face, as defined by the descriptors defined in the CSS ''@font-face'' rule. They are parsed the same as the corresponding ''@font-face'' descriptors. They are used by the font matching algorithm, but otherwise have no effect. For example, a {{FontFace}} with a {{FontFace/style}} of "italic" represents an italic font face; it does not make the font face italic. On getting, return the string associated with this attribute. On setting, [=CSS/parse=] the string according to the grammar for the corresponding ''@font-face'' descriptor. If it does not match the grammar, throw a {{SyntaxError}}; otherwise, set the attribute to the serialization of the parsed value. : variant : featureSettings : variationSettings : display :: These attributes have the same meaning, and are parsed the same as, the corresponding descriptors in the CSS ''@font-face'' rules. They turn on or off specific features in fonts that support them. Unlike the previous attributes, these attributes actually affect the font face. On getting, return the string associated with this attribute. On setting, [=CSS/parse=] the string according to the grammar for the corresponding ''@font-face'' descriptor. If it does not match the grammar, throw a {{SyntaxError}}; otherwise, set the attribute to the serialization of the parsed value. : status :: This attribute reflects the current status of the font face. It must be "unloaded" for a newly-created {{FontFace}}. It can change due to an author explicitly requesting a font face to load, such as through the {{FontFace/load()}} method on {{FontFace}}, or implicitly by the user agent, due to it detecting that the font face is needed to draw some text on the screen. : loaded :: This attribute reflects the {{[[FontStatusPromise]]}} of the font face.

The Constructor

The load() method

Interaction with CSS’s ''@font-face'' Rule

The FontFaceSet Interface

: ready :: This attribute reflects the {{FontFaceSet}}'s {{[[ReadyPromise]]}} slot. See [[#font-face-set-ready]] for more details on this {{Promise}} and its use. : FontFaceSet(initialFaces) :: The {{FontFaceSet}} constructor, when called, must iterate its {{initialFaces}} argument and add each value to its [=FontFaceSet/set entries=]. : iteration order :: When iterated over, all CSS-connected {{FontFace}} objects must come first, in document order of their connected ''@font-face'' rules, followed by the non-CSS-connected {{FontFace}} objects, in insertion order. : set entries :: If a {{FontFaceSet}} is a font source, its set entries are initialized as specified in [[#document-font-face-set]]. Otherwise, its set entries are initially empty. : add(font) :: When the {{add()}} method is called, execute the following steps: 1. If font is already in the {{FontFaceSet}}’s [=FontFaceSet/set entries=], skip to the last step of this algorithm immediately. 2. If font is CSS-connected, throw an {{InvalidModificationError}} exception and exit this algorithm immediately. 3. Add the font argument to the {{FontFaceSet}}’s [=FontFaceSet/set entries=]. 2. If font’s {{FontFace/status}} attribute is "loading": 1. If the {{FontFaceSet}}’s {{[[LoadingFonts]]}} list is empty, switch the FontFaceSet to loading. 2. Append font to the {{FontFaceSet}}’s {{[[LoadingFonts]]}} list. 3. Return the {{FontFaceSet}}. : delete(font) :: When the {{delete()}} method is called, execute the following steps: 1. If font is CSS-connected, return false and exit this algorithm immediately. 2. Let deleted be the result of removing font from the {{FontFaceSet}}’s [=FontFaceSet/set entries=]. 3. If font is present in the {{FontFaceSet}}’s {{[[LoadedFonts]]}}, or {{[[FailedFonts]]}} lists, remove it. 4. If font is present in the {{FontFaceSet}}’s {{[[LoadingFonts]]}} list, remove it. If font was the last item in that list (and so the list is now empty), switch the FontFaceSet to loaded. 5. Return deleted. : clear() :: When the {{clear()}} method is called, execute the following steps: 1. Remove all items from the {{FontFaceSet}}’s [=FontFaceSet/set entries=], its {{[[LoadedFonts]]}} list, and its {{[[FailedFonts]]}} list. 2. If the {{FontFaceSet}}’s {{[[LoadingFonts]]}} list is non-empty, remove all items from it, then switch the FontFaceSet to loaded.

Events

Event handler	Event handler event type
{{onloading}}	{{loading!!event}}
{{onloadingdone}}	{{loadingdone}}
{{onloadingerror}}	{{loadingerror}}

The load() method

The check() method

Two special cases in this method's behavior should be noted, as they are non-obvious: * If the specified fonts exist, but all possible faces are ruled out due to their unicode-range not covering the provided text, the method returns true, as the text will be rendered in the UA's fallback font instead, and won't trigger any font loads. * If none of the specified fonts exist, even though this is technically similar to the previous case (in that text rendered with that font list would just use the UA fallback font), the method instead throws an error. This is because such a situation is almost certainly either a typo, or the result of changing the name of a downloadable font and forgetting to update all places the old name was used, and an error is more useful than a vacuous true.

The ready attribute

Interaction with CSS Font Loading and Matching

Fonts are available when they are added to a {{FontFaceSet}}. Adding a new ''@font-face'' rule to a stylesheet also adds a new {{FontFace}} to the {{FontFaceSet}} of the {{Document}} object. Adding a new ''@font-face'' rule:

		document.styleSheets[0].insertRule(
			"@font-face { font-family: newfont; src: url(newfont.woff); }", 0);
		document.body.style.fontFamily = "newfont, serif";

Constructing a new {{FontFace}} object and adding it to document.fonts:

		var f = new FontFace("newfont", "url(newfont.woff)");
		document.fonts.add(f);
		document.body.style.fontFamily = "newfont, serif";

In both cases, the loading of the font resource “newfont.woff” will be initiated by the layout engine, just as other ''@font-face'' rule fonts are loaded. Omitting the addition to document.fonts means the font would never be loaded and text would be displayed in the default serif font:

		var f = new FontFace("newfont", "url(newtest.woff)", {});

		/* new {{FontFace}} not added to {{FontFaceSet}},
		   so the 'font-family' property can't see it,
		   and serif will be used instead */
		document.body.style.fontFamily = "newfont, serif";

To explicitly preload a font before using it, authors can defer the addition of a new {{FontFace}} to a {{FontFaceSet}} until the load has completed:

		var f = new FontFace("newfont", "url(newfont.woff)", {});
		f.load().then(function (loadedFace) {
			document.fonts.add(loadedFace);
			document.body.style.fontFamily = "newfont, serif";
		});

In this case, the font resource “newfont.woff” is first downloaded. Once the download completes, the font is added to the document's {{FontFaceSet}}, the body font is changed, and the layout engine uses the new font resource.

The FontFaceSource interface

Worker FontFaceSources

Interaction with CSS’s ''@font-face'' Rule

API Examples

A rich text editing application may need to measure text elements after editing operations have taken place. Since style changes may or may not require additional fonts to be downloaded, or the fonts may already have been downloaded, the measurement procedures need to occur after those font loads complete:

			function measureTextElements() {
				// contents can now be measured using the metrics of
				// the downloadable font(s)
			}

			function doEditing() {
				// content/layout operations that may cause additional font loads
				document.fonts.ready.then(measureTextElements);
			}

The {{loadingdone}} event only fires after all font related loads have completed and text has been laid out without causing additional font loads:

			<style>
			@font-face {
				font-family: latin-serif;
				src: url(latinserif.woff) format("woff"); /* contains no kanji/kana */
			}
			@font-face {
				font-family: jpn-mincho;
				src: url(mincho.woff) format("woff");
			}
			@font-face {
				font-family: unused;
				src: url(unused.woff);
			}

			body { font-family: latin-serif, jpn-mincho; }
			</style>
			<p>納豆はいかがでしょうか

In this situation, the user agent first downloads “latinserif.woff” and then tries to use this to draw the Japanese text. But because no Japanese glyphs are present in that font, fallback occurs and the font “mincho.woff” is downloaded. Only after the second font is downloaded and the Japanese text laid out does the {{loadingdone}} event fire. The "unused" font isn't loaded, but no text is using it, so the UA isn't even trying to load it. It doesn't interfere with the {{loadingdone}} event.

Introduction

Values

Task Sources

The `FontFace` Interface

The Constructor

The `load()` method

Interaction with CSS’s ''@font-face'' Rule

The `FontFaceSet` Interface

Events

The `load()` method

The `check()` method

The `ready` attribute

Interaction with CSS Font Loading and Matching

The `FontFaceSource` interface

Worker FontFaceSources

Interaction with CSS’s ''@font-face'' Rule

API Examples

Changes

Acknowledgments

Privacy & Security Considerations

Introduction

Values

Task Sources

The FontFace Interface

The Constructor

The load() method

Interaction with CSS’s ''@font-face'' Rule

The FontFaceSet Interface

Events

The load() method

The check() method

The ready attribute

Interaction with CSS Font Loading and Matching

The FontFaceSource interface

Worker FontFaceSources

Interaction with CSS’s ''@font-face'' Rule

API Examples

Changes

Acknowledgments

Privacy & Security Considerations

The `FontFace` Interface

The `load()` method

The `FontFaceSet` Interface

The `load()` method

The `check()` method

The `ready` attribute

The `FontFaceSource` interface