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.
@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.
Syntax
@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
woff2source is normally enough. - Choose
font-displaydeliberately.swapshows text quickly but may shift the layout;optionalavoids 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 thecrossoriginattribute even on the same origin. - Cross-origin fonts need CORS headers (
Access-Control-Allow-Origin) from the font host. - Subset with
unicode-rangeso visitors download only the scripts they need. - Match the family name exactly in
font-familyand always add a generic fallback such assans-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.
Related
@font-feature-values@font-palette-values@supports- Lesson: Web Fonts
- Lesson: Fonts