CSS @font-face Rule

CSS @font-face Rule

The CSS @font-face rule defines a custom font and tells the browser where the font resource can be found.

After a font is defined with @font-face, its assigned family name can be used with the font-family property just like other fonts. The rule can also describe the font's weight, style, display behavior, and other characteristics.

@font-face Syntax

The @font-face rule contains descriptors that describe a font face and identify the resource the browser can use to load it.

@font-face {
  font-family: "CustomFont";
  src: url("CustomFont.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

Unlike a normal CSS ruleset, @font-face does not select an HTML element. It defines a font resource that can later be selected through properties such as font-family, font-weight, and font-style.

font-family Descriptor

The font-family descriptor gives the font face a name that can be referenced elsewhere in your CSS.

@font-face {
  font-family: "Mailman";
  src: url("Mailman-Regular.woff2") format("woff2");
}

The name does not have to match the font filename, but using a meaningful family name makes the stylesheet easier to understand and maintain.

After defining the family, the same name can be used with the font-family property.

h2 {
  font-family: "Mailman", cursive;
}

src Descriptor

The src descriptor identifies one or more font resources that the browser can use.

src: url("Mailman-Regular.woff2") format("woff2");

The url() function specifies the location of the font file. Relative URLs are resolved relative to the stylesheet containing the @font-face rule.

A local font can also be listed with local(), allowing the browser to use an installed copy before downloading a font file.

src: local("Mailman"),
     url("Mailman-Regular.woff2") format("woff2");

Font Format

The optional format() function provides the browser with information about the format of the font resource.

src: url("Mailman-Regular.woff2") format("woff2");

WOFF2 is generally preferred for modern websites because it provides efficient compression and broad support in current browsers. WOFF may also be supplied when support for older browsers is needed.

font-weight Descriptor

The font-weight descriptor tells the browser which weight the font face represents.

@font-face {
  font-family: "CustomFont";
  src: url("CustomFont-Bold.woff2") format("woff2");
  font-weight: 700;
}

When CSS later requests font-weight: 700, the browser can match that request with the appropriate font face.

For a regular font face, the weight is commonly 400. A bold font face is commonly 700.

font-style Descriptor

The font-style descriptor identifies whether a font face represents normal, italic, or oblique text.

@font-face {
  font-family: "CustomFont";
  src: url("CustomFont-Italic.woff2") format("woff2");
  font-weight: 400;
  font-style: italic;
}

Describing the font face correctly allows the browser to choose it when the corresponding font-style is requested.

font-display Descriptor

The font-display descriptor controls how the browser handles text while a downloadable font is loading or unavailable.

@font-face {
  font-family: "CustomFont";
  src: url("CustomFont-Regular.woff2") format("woff2");
  font-display: swap;
}

The best value depends on the purpose of the font and the experience you want while it is loading. For many ordinary web font uses, swap keeps text visible by allowing a fallback font to appear first.

Multiple Font Sources

The src descriptor can contain multiple font sources separated by commas. The browser checks the sources in order and uses the first suitable source it can load.

@font-face {
  font-family: "CustomFont";
  src: url("CustomFont.woff2") format("woff2"),
       url("CustomFont.woff") format("woff");
}

For modern websites, WOFF2 should normally appear before WOFF so browsers that support WOFF2 can use the smaller, more efficient format.

Multiple Font Faces

A font family may have separate files for regular, bold, italic, and other variations. Define each variation with its own @font-face rule while using the same family name.

@font-face {
  font-family: "CustomFont";
  src: url("CustomFont-Regular.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
}
@font-face {
  font-family: "CustomFont";
  src: url("CustomFont-Bold.woff2") format("woff2");
  font-weight: 700;
  font-style: normal;
}

The browser uses the descriptors to match the requested weight and style with the appropriate font file.

Using the Font

Defining a font with @font-face makes the font available to CSS, but it does not automatically apply the font to any elements.

Use the assigned family name with font-family wherever the custom font should appear.

h1, h2 {
  font-family: "CustomFont", sans-serif;
}

For a decorative custom font, you might apply the family only to headings while continuing to use a standard system font for body text.

body {
  font-family: Arial, Helvetica, sans-serif;
}
h1, h2 {
  font-family: "CustomFont", cursive;
}

This keeps the custom font focused on the part of the design where its distinctive appearance adds value.

@font-face Example

The following example defines the self-hosted Mailman script font with @font-face and applies it only to the decorative heading. The body text continues to use Arial.

@font-face {
  font-family: "Mailman";
  src: url("web-fonts/Mailman-Regular.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}
.mailman {
  font-family: "Mailman", cursive;
}

Open the example in the editor and examine the @font-face rule. Try changing the family name in both locations to see how the name defined by @font-face connects the font resource to the font-family property.