FontFace

Constructor

FontFace()

Constructs and returns a new FontFace object, built from an external resource described by a URL or from an ArrayBuffer.

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 current FontFace object when the font specified in the object's constructor is done loading or rejects with a SyntaxError 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

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 "my-font.woff" with a few font descriptors. Just to show how it works, we then define the stretch descriptor using a property.

// Define a FontFace
const font = new FontFace("my-font", 'url("my-font.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.

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

Browser compatibility

See also

• @font-face