W3cubDocs

/Web APIs

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

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
FontFace 35 79 41 No 22 10 37 35 41 22 10 4.0
FontFace 35 79 41 No 22 10 37 35 41 22 10 4.0
ascentOverride 87 87 89 No 73 No 87 87 89 62 No 14.0
descentOverride 87 87 89 No 73 No 87 87 89 62 No 14.0
display 60 79 58 No 47 11.1 60 60 58 44 11.3 8.0
family 35 79 41 No 22 10 37 35 41 22 10 4.0
featureSettings 35 79 41 No 22 10 37 35 41 22 10 4.0
lineGapOverride 87 87 89 No 73 No 87 87 89 62 No 14.0
load 35 79 41 No 22 10 37 35 41 22 10 4.0
loaded 37 79 41 No 24 10 37 37 41 24 10 4.0
status 35 79 41 No 22 10 37 35 41 22 10 4.0
stretch 35 79 41 No 22 10 37 35 41 22 10 4.0
style 35 79 41 No 22 10 37 35 41 22 10 4.0
unicodeRange 35 79 41 No 22 10 37 35 41 22 10 4.0
variant 35 79 41 No 22 10–13.1 37 35 41 22 10–13.4 4.0
variationSettings No No 62 No No No No No 62 No No No
weight 35 79 41 No 22 10 37 35 41 22 10 4.0
worker_support 69 79 105 No 56 No 69 69 105 48 No 10.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/FontFace