Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท At-rules

The @font-face at-rule

Reference for the CSS @font-face at-rule: define custom fonts, src formats, font-display, unicode-range and size-adjust, with live examples.

The @font-face at-rule defines a font family name and tells the browser where to get the font data. After that you can use the name in font-family like any other font. The browser downloads a font file only when text on the page actually needs it.

Each @font-face block describes one face (one weight, style and width of a family). To offer regular and bold, write two blocks with the same font-family and different font-weight.

CSS
@font-face {
  font-family: "Brand";
  src: url("/fonts/brand.woff2") format("woff2");
  font-weight: 400;
  font-display: swap;
}

Try it

The preview has no font files, so this example uses local() to point at fonts already installed, and unicode-range to restyle only the digits.

A face used only for digits

Syntax

CSS
@font-face {
  font-family: <name>;
  src: <source>#;                 /* url(...) format(...) tech(...), local(...) */
  font-weight: <weight> | <range>;
  font-style: normal | italic | oblique <angle>?;
  font-stretch: <percentage> | <range>;
  font-display: auto | block | swap | fallback | optional;
  unicode-range: <range>#;
  size-adjust: <percentage>;
  ascent-override: <percentage>;
  descent-override: <percentage>;
  line-gap-override: <percentage>;
  font-variation-settings: <settings>;
}

src and font-family are required. These are descriptors, not properties, so they do not inherit or animate.

Values

Value Description
src: url(f.woff2) format("woff2") Download this file. List the best format first.
src: local("Name") Use an installed font by full or PostScript name.
font-weight: 100 900 A range, for variable fonts.
font-display: swap Show fallback text at once, swap when the font arrives.
font-display: optional Use the font only if already available; no layout shift.
unicode-range: U+0000-00FF Use this face only for these code points (subsetting).
size-adjust: 105% Scale glyphs, useful to match a fallback font's metrics.
*-override Adjust ascent, descent and line gap to reduce layout shift.

Usage notes

  • Use WOFF2. It is supported everywhere and compresses best; one woff2 source is normally enough.
  • Choose font-display deliberately. swap shows text quickly but may shift the layout; optional avoids the shift but may skip the font on a first visit.
  • Preload critical fonts with <link rel="preload" as="font" type="font/woff2" crossorigin>; fonts need the crossorigin attribute even on the same origin.
  • Cross-origin fonts need CORS headers (Access-Control-Allow-Origin) from the font host.
  • Subset with unicode-range so visitors download only the scripts they need.
  • Match the family name exactly in font-family and always add a generic fallback such as sans-serif.
  • Licensing. Check that your font license allows web embedding.
  • Variable fonts let one file cover many weights; declare the range in font-weight.

Browser support

Supported in every browser; WOFF2 everywhere. The metric override descriptors (size-adjust, ascent-override) are newer and are not available in every browser, but are safely ignored where unsupported.