CSS src Descriptor
The CSS src
descriptor is used with the @font-face
at-rule to specify the resource containing font data.
The @font-face
rule accepts a number of descriptors that define the location of a font resource, either locally or externally, along with the style characteristics of an individual face. These descriptors apply solely within the context of the @font-face
rule in which they are defined.
The src
descriptor is a required descriptor of the @font-face
rule (as is the font-family
descriptor).
Here's an example of using the src
descriptor.
When the user visits a page that uses a font called "Goudy", the browser will download the font file from "http://example.com/fonts/goudy.woff".
Absolute vs Relative URLs
The above example uses an absolute URL. That is, the full location of the font file is supplied, including the website's domain name and the http protocol.
As with any CSS url data type, you can also use a relative URL. You can also surround the URL with quotes or double quotes if you wish. So the following are all valid URLs:
Just be sure that the font actually exists at the location you specify.
Providing a List of Font Files
You can also provide a list of fonts to the src
descriptor. The user agent/browser will iterate over the list and use the first one it can successfully activate. If it can't activate a font (or if it doesn't exist), it will progress to the next one on the list, and so on.
Here's an example:
In this case, the same font is supplied in two formats; WOFF format and OpenType format. The WOFF format is our first choice. If that can't be activated for some reason, the user agent will try the OpenType format instead.
Providing a Format Hint
The src
descriptor accepts an optional format hint. This enables you to explicitly state the font format that the font file uses. You do this with the format()
functional notation. Like this:
Specifying a Local Copy of the Font (if Available)
By default, if the name you give to a font is the same as a font on the user's computer, your font will be used instead of the user's local copy. However, you can change this behavior if required.
You can use local()
to specify that the user's copy of the font should be used first (if they have it). You can follow this up with a url()
so that the user agent can download your copy if a local copy isn't available.
Font 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 |
Official Syntax
The src
descriptor has the following syntax:
- url
- Specifies the location of the font file on the web. Can be any valid url. It can be an absolute or relative location. It can also be enclosed in quotes, double quotes, but this is not required.
- [format(string #)]?
-
This is an optional format hint. It provides the user agent with a hint as to the format of the file. This can be a comma-separated list of format strings that denote well-known font formats. The user agent won't download any unsupported fonts or fonts of an unknown format. If not format hint is supplied, the user agent will download the file, even it it's unsupported or of an unknown format.
This value takes the form of
format()
with a valid string being passed in to indicate the format. - font-face-name
- This is a format-specific string that uniquely identifies a single font face within a larger family. It must be a unique font face name enclosed by
local(
and)
(for examplelocal(Garamond)
. The name can optionally be enclosed in quotes.
Official Specifications
The src
descriptor is defined in CSS Fonts Module Level 3 (W3C Candidate Recommendation 3 October 2013).