CSS @font-face At-Rule

The CSS @font-face at-rule can be used to specify a custom font so that you aren't solely reliant on the fonts that are installed on the user's computer.

The @font-face at-rule allows you to select from a wider range of fonts than would normally be available if relying solely on the user's system fonts.

Fonts specified with the @font-face at-rule are only fetched and activated if they are used within the HTML document. This is good for performance, as the font is not downloaded unless its needed.

Here's an example of using the @font-face at-rule:

In this example I use @font-face to retrieve the font. I use "Open Sans" as the font family. I then refer to that font family when I use that font for the body element.

Without using @font-face, the font that the user sees will be limited to the fonts installed on their device. So if I hadn't used @font-face to retrieve the font, specifying "Open Sans" for the body element would only work if the user had that font installed on their device. If not, their browser would use the default sans-serif font (because I specified sans-serif). Many systems use Helvetica or Arial as the default sans-serif font, however, there's no guarantee that even those fonts will be installed on the user's system.

Using Multiple File Formats

You can provide a list of font formats for failover purposes. If the user's system doesn't support one format, it may support the next one on your list, and so on.

Here's an example:

The above example uses the local() function to retrieve the font from the user's local system. If it's not found, it will look for the next option — in this case the .woff2 option. If the system doesn't support that font format, it will use the .woff option. If it doesn't support that option, it will use the .ttf option.

If none of those options work, the body element will end up using the default sans-serif font on the user's system.

Formats

The format strings defined by CSS are as follows:

String	Font Format	Common Extensions
`"woff"`	WOFF (Web Open Font Format)	.woff
`"truetype"`	TrueType	.ttf
`"opentype"`	OpenType	.ttf, .otf
`"embedded-opentype"`	Embedded OpenType	.eot
`"svg"`	SVG Font	.svg, .svgz

Possible Values

The @font-face rule accepts the following descriptors, which define the location of a font resource, either locally or externally, along with the style characteristics of an individual face.

font-family

This is the font-family descriptor, which defines the font family name that will be used in all CSS font family name matching. This is the name that you refer to within your CSS declarations whenever you want to refer to that font.

This descriptor is required.

src

This is the src descriptor, which specifies the resource containing font data. Its value is a prioritized, comma-separated list of external references or locally-installed font face names. When a font is needed the user agent iterates over the set of references listed, using the first one it can successfully activate. Fonts containing invalid data or local font faces that are not found are ignored and the user agent loads the next font in the list.

This descriptor is required.

The official syntax is:

font-style

This is the font-style descriptor, which defines a value that will be used when matching styles to specific faces.

Possible values:

normal
italic
oblique

The default value is normal.

font-weight

This is the font-weight descriptor, that defines a value that will be used when matching styles to specific faces.

Possible values:

normal
bold
100
200
300
400
500
600
700
800
900

The default value is normal.

font-stretch

This is the font-stretch descriptor, which defines a value that will be used when matching styles to specific faces.

normal
ultra-condensed
extra-condensed
condensed
semi-condensed
semi-expanded
expanded
extra-expanded
ultra-expanded

The default value is normal.

unicode-range

This is the unicode-range descriptor, which defines the set of Unicode codepoints that may be supported by the font face for which it is declared. Can be specified as a single codepoint or a range of codepoints. Here's how that works:

Single codepoint: A Unicode codepoint, represented as one to six hexadecimal digits. Example: U+1F41D (represents the the HONEYBEE emoji icon).
Interval range: Represented as two hyphen-separated Unicode codepoints indicating the inclusive start and end codepoints of a range. Example: U+25A0-25FF (range for the geometric shapes).
Wildcard range: Defined by the set of codepoints implied when trailing ? characters signify any hexadeximal digit. Example: U+30?? (range for the hiragana characters).

font-variant

This is the font-variant descriptor, which defines the initial settings that apply when the font is rendered.

This descriptor accepts the following values:

normal | none | [ <common-lig-values> || <discretionary-lig-values> || <historical-lig-values> || <contextual-alt-values> || stylistic(<feature-value-name>) || historical-forms || styleset(<feature-value-name> #) || character-variant(<feature-value-name> #) || swash(<feature-value-name>) || ornaments(<feature-value-name>) || annotation(<feature-value-name>) || [ small-caps | all-small-caps | petite-caps | all-petite-caps | unicase | titling-caps ] || <numeric-figure-values> || <numeric-spacing-values> || <numeric-fraction-values> || ordinal || slashed-zero || <east-asian-variant-values> || <east-asian-width-values> || ruby ]

See the font-variant descriptor for more information about these values.

font-feature-settings

This is the font-feature-settings descriptor, which defines the initial settings that apply when the font is rendered.

Allows you to specify an OpenType feature tag. This is defined as follows:

And <feature-tag-value> is defined as follows:

A <string> is a case-sensitive OpenType feature tag. Feature tags contain four ASCII characters.

Here's a full list of OpenType feature tags.

Lazy Loading

The @font-face at-rule is designed to allow lazy loading of font resources that are only downloaded when used within a document. What this means is that the font is only downloaded if the font is needed in the document. If the page doesn't contain any elements that use the font, it won't be downloaded.

Consider this example:

The font "Happy Monkey" will only be downloaded if the HTML document contains an aside element. If not, the font won't be downloaded.

The font may also be downloaded even if "Happy Monkey" is not the first choice font. For example, it may be downloaded in this case:

Official Specifications

The @font-face at-rule is defined in CSS Fonts Module Level 3 (W3C Candidate Recommendation 3 October 2013).

WOFF File Format Specifications

The WOFF file format was initially defined in WOFF File Format 1.0 (W3C Recommendation 13 December 2012). This document specifies the WOFF font packaging format.

The WOFF2 file format is defined in WOFF File Format 2.0 (W3C Candidate Recommendation 15 March 2016). This specification was developed to provide improved compression for the WOFF file format, and thus lower use of network bandwidth, while still allowing fast decompression even on mobile devices.