FontFace
The FontFace
interface of the CSS Font Loading API represents a single usable font face.
This interface defines the source of a font face, either a URL to an external resource or a buffer, and font properties such as style
, weight
, and so on.
For URL font sources it allows authors to trigger when the remote font is fetched and loaded, and to track loading status.
Constructor
FontFace()
-
Constructs and returns a new
FontFace
object, built from an external resource described by a URL or from anArrayBuffer
.
Instance properties
FontFace.ascentOverride
-
A string that retrieves or sets the ascent metric of the font. It is equivalent to the
ascent-override
descriptor. FontFace.descentOverride
-
A string that retrieves or sets the descent metric of the font. It is equivalent to the
descent-override
descriptor. FontFace.display
-
A string that determines how a font face is displayed based on whether and when it is downloaded and ready to use.
FontFace.family
-
A string that retrieves or sets the family of the font. It is equivalent to the
font-family
descriptor. FontFace.featureSettings
-
A string that retrieves or sets infrequently used font features that are not available from a font's variant properties. It is equivalent to the CSS
font-feature-settings
property. FontFace.lineGapOverride
-
A string that retrieves or sets the line-gap metric of the font. It is equivalent to the
line-gap-override
descriptor. FontFace.loaded
Read only-
Returns a
Promise
that resolves with the currentFontFace
object when the font specified in the object's constructor is done loading or rejects with aSyntaxError
DOMException
. FontFace.status
Read only-
Returns an enumerated value indicating the status of the font, one of
"unloaded"
,"loading"
,"loaded"
, or"error"
. FontFace.stretch
-
A string that retrieves or sets how the font stretches. It is equivalent to the
font-stretch
descriptor. FontFace.style
-
A string that retrieves or sets the style of the font. It is equivalent to the
font-style
descriptor. FontFace.unicodeRange
-
A string that retrieves or sets the range of unicode code points encompassing the font. It is equivalent to the
unicode-range
descriptor. FontFace.variant
-
A string that retrieves or sets the variant of the font.
FontFace.variationSettings
Experimental-
A string that retrieves or sets the variation settings of the font. It is equivalent to the
font-variation-settings
descriptor. FontFace.weight
-
A string that contains the weight of the font. It is equivalent to the
font-weight
descriptor. FontFace.load()
-
Loads a font based on current object's constructor-passed requirements, including a location or source buffer, and returns a
Promise
that resolves with the current FontFace object.
Examples
The code below defines a font face using data at the URL "myfont.woff" with a few font descriptors.
Just to show how it works, we then define the stretch
descriptor using a property.
js
//Define a FontFace
const font = new FontFace("myfont", "url(myfont.woff)", {
style: "italic",
weight: "400",
});
font.stretch = "condensed";
Next we load the font using FontFace.load()
and use the returned promise to track completion or report an error.
js
//Load the font
font.load().then(
() => {
// Resolved - add font to document.fonts
},
(err) => {
console.error(err);
}
);
To actually use the font we will need to add it to a FontFaceSet
.
We could do that before or after loading the font.
For additional examples see CSS Font Loading API > Examples.
Specifications
Specification |
---|
CSS Font Loading Module Level 3 # fontface-interface |
Browser compatibility
BCD tables only load in the browser