diff --git a/files/en-us/web/css/@font-face/index.md b/files/en-us/web/css/@font-face/index.md index e0c914fec191674..656936ca326d2c4 100644 --- a/files/en-us/web/css/@font-face/index.md +++ b/files/en-us/web/css/@font-face/index.md @@ -58,65 +58,7 @@ The **`@font-face`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/At - {{cssxref("@font-face/size-adjust", "size-adjust")}} - : Defines a multiplier for glyph outlines and metrics associated with this font. This makes it easier to harmonize the designs of various fonts when rendered at the same font size. - {{cssxref("@font-face/src", "src")}} - - - : Specifies font resources. - - A comma-separated list representing the resource fallback order, where each resource is specified using `url()` or `local()`. - The first resource in the list that loads successfully will be used and subsequent items are ignored. - If multiple `src` descriptors are set, only the last declared rule that is able to load a resource is applied. - - > **Note:** Items that the browser considers invalid are ignored. - > Some browsers will ignore the whole descriptor if any item is invalid, even if only one item is invalid. - > This may affect design of your fallbacks. - - The `url()` can be followed by `format()` and `tech()`, like this: - - ```css - src: local("Trickster"), - url("trickster-COLRv1.otf") format("opentype") tech(color-COLRv1), url("trickster-outline.otf") - format("opentype"), url("trickster-outline.woff") format("woff"); - ``` - - `url()`: Specifies the URL of a font file, like any other `url()` in CSS. If the font file is a container for multiple fonts, a fragment identifier is included to indicate which sub-font should be used, as follows: - - ```css - src: url(collection.otc#WhichFont); /* WhichFont is the PostScript name of a font in the font file */ - src: url(fonts.svg#WhichFont); /* WhichFont is the element id of a font in the SVG Font file */ - ``` - - `local()`: Specifies the font name should the font be available on the user's device. Quoting the font name is optional. - - > **Note:** The {{domxref("Local Font Access API", "Local Font Access API", "", "nocode")}} can be used to access the user's locally installed font data — this includes higher-level details such as names, styles, and families, as well as the raw bytes of the underlying font files. - - `format()`: **Optional**. Specifies the font format. If the value is not supported or invalid, the browser may not download the resource, potentially saving bandwidth. If omitted, the browser will always download the resource and then detect the format. The preferred value type is a _keyword_, which can also be given as a _string_ (within quotes) for backward compatibility reasons. - - The following table shows the valid values and their corresponding font formats. There are a few other possible values, see next paragraph. - - | Keyword | Font Format | Common extensions | - | ------------------- | --------------------- | ----------------- | - | `woff2` | WOFF 2.0 | .woff2 | - | `woff` | WOFF 1.0 | .woff | - | `opentype` | OpenType | .otf, .ttf | - | `truetype` | TrueType | .ttf | - | `collection` | OpenType Collection | .otc, .ttc | - | `embedded-opentype` | Embedded OpenType | .eot | - | `svg` | SVG Font (deprecated) | .svg, .svgz | - - > **Note:** The values `opentype` and `truetype` are completely equivalent, regardless of whether the font file uses cubic bezier curves (within CFF/CFF2 table) or quadratic bezier curves (within glyph table). - - `tech()`: **Optional**. {{Experimental_inline}} Value is one of the following _keywords_: `variations`, `palettes`, `incremental`, `features-opentype`, `features-aat`, `features-graphite`, `color-COLRv0`, `color-COLRv1`, `color-SVG`, `color-sbix`, `color-CBDT`. - - The following table shows several old unnormalized `format()` values and their new equivalent syntax: - - | Old syntax | Equivalent syntax | - | ------------------------------- | ----------------------------------- | - | `format("woff2-variations")` | `format(woff2) tech(variations)` | - | `format("woff-variations")` | `format(woff) tech(variations)` | - | `format("opentype-variations")` | `format(opentype) tech(variations)` | - | `format("truetype-variations")` | `format(truetype) tech(variations)` | - - > **Note:** `format(svg)` stands for [SVG fonts](/en-US/docs/Web/SVG/Tutorial/SVG_fonts), and `tech(color-SVG)` stands for [OpenType fonts with SVG table](https://learn.microsoft.com/en-us/typography/opentype/spec/svg) (also called OpenType-SVG color fonts), which are completely different. - + - : Specifies references to font resources including hints about the font format and technology. It is required for the @font-face rule to be valid. - {{cssxref("@font-face/unicode-range", "unicode-range")}} - : The range of Unicode code points to be used from the font. @@ -129,7 +71,9 @@ If the `local()` function is provided, specifying a font name to look for on the Browsers attempt to load resources in their list declaration order, so usually `local()` should be written before `url()`. Both functions are optional, so a rule block containing only one or more `local()` without `url()` is possible. If a more specific fonts with `format()` or `tech()` values are desired, these should be listed _before_ versions that don't have these values, as the less-specific variant would otherwise be tried and used first. -By allowing authors to provide their own fonts, `@font-face` makes it possible to design content without being limited to the so-called "web-safe" fonts (that is, the fonts which are so common that they're considered to be universally available). The ability to specify the name of a locally-installed font to look for and use makes it possible to customize the font beyond the basics while making it possible to do so without relying on an Internet connection. +By allowing authors to provide their own fonts, `@font-face` makes it possible to design content without being limited to the so-called "web-safe" fonts (that is, the fonts which are so common that they're considered to be universally available). The ability to specify the name of a locally-installed font to look for and use makes it possible to customize the font beyond the basics while making it possible to do so without relying on an internet connection. + +> **Note:** Fallback strategies for loading fonts on older browsers are described in the [`src` descriptor page](/en-US/docs/Web/CSS/@font-face/src#fallbacks_for_older_browsers). The `@font-face` at-rule may be used not only at the top level of a CSS, but also inside any [CSS conditional-group at-rule](/en-US/docs/Web/CSS/At-rule#conditional_group_rules). @@ -209,36 +153,6 @@ In this example, the user's local copy of "Helvetica Neue Bold" is used; if the } ``` -### Fallbacks on older browsers - -Browsers should use a `@font-face` with a single `src` descriptor listing possible sources for the font. -Since the browser will use the first resource that it is able to load, items should be specified in the order that you'd most like them to be used. - -Generally this means that local files should appear before remote files, and that resources with `format()` or `tech()` constraints should appear before resources that don't have them (otherwise the less-constrained version would always be selected). -For example: - -```css -@font-face { - font-family: "MgOpenModernaBold"; - src: url("MgOpenModernaBoldIncr.otf") format("opentype") tech(incremental), url("MgOpenModernaBold.otf") format(opentype); -} -``` - -A browser that does not support `tech()` above should drop the first item and attempt to load the second resource. - -Some browsers do not yet [drop invalid items](#browser_compatibility), and instead fail the whole `src` descriptor if any value is invalid. -If working with these browsers you can specify multiple `src` descriptors as fallbacks. -Note that multiple `src` descriptors are attempted in reverse-order, so at the end we have our normal descriptor with all the items. - -```css -@font-face { - font-family: "MgOpenModernaBold"; - src: url("MgOpenModernaBold.otf") format(opentype); - src: url("MgOpenModernaBoldIncr.otf") format("opentype") tech(incremental); - src: url("MgOpenModernaBoldIncr.otf") format("opentype") tech(incremental), url("MgOpenModernaBold.otf") format(opentype); -} -``` - ## Specifications {{Specifications}} diff --git a/files/en-us/web/css/@font-face/src/index.md b/files/en-us/web/css/@font-face/src/index.md index 83833ab6b21df61..104f7fa8a409e1c 100644 --- a/files/en-us/web/css/@font-face/src/index.md +++ b/files/en-us/web/css/@font-face/src/index.md @@ -23,35 +23,128 @@ The **`src`** CSS descriptor of the {{cssxref("@font-face")}} rule specifies the /* values */ src: url(https://somewebsite.com/path/to/font.woff); /* Absolute URL */ src: url(path/to/font.woff); /* Relative URL */ -src: url(path/to/font.woff) format("woff"); /* Explicit format */ src: url("path/to/font.woff"); /* Quoted URL */ -src: url(path/to/svgfont.svg#example); /* Fragment identifying font */ +src: url(path/to/svgFont.svg#example); /* Fragment identifying font */ /* values */ src: local(font); /* Unquoted name */ src: local(some font); /* Name containing space */ src: local("font"); /* Quoted name */ +src: local('some font'); /* Single-quoted name containing a space */ -/* Multiple items */ -src: local(font), url(path/to/font.svg) format("svg"), url(path/to/font.woff) - format("woff"), url(path/to/font.otf) format("opentype"); +/* )> values */ +src: url(path/to/fontCOLRv1.otf) tech(color-COLRv1); +src: url(path/to/fontCOLR-svg.otf) tech(color-SVG); + +/* )> values */ +src: url(path/to/font.woff) format("woff"); +src: url(path/to/font.otf) format("opentype"); + +/* Multiple resources */ +src: url(path/to/font.woff) format("woff"), url(path/to/font.otf) format("opentype"); + +/* Multiple resources with font format and technologies */ +src: url("trickster-COLRv1.otf") format(opentype) tech(color-COLRv1), url("trickster-outline.otf") + format(opentype); ``` ### Values -- ` [ format( # ) ]?` - - : Specifies an external reference consisting of a {{cssxref("<url>")}}, followed by an optional hint using the `format()` function to describe the format of the font resource referenced by that URL. The format hint contains a comma-separated list of format strings that denote well-known font formats. If a user agent doesn't support the specified formats, it skips downloading the font resource. If no format hints are supplied, the font resource is always downloaded. +- `url()` + + - : Specifies an external reference consisting of a {{cssxref("<url>")}}, followed by optional hints using the `format()` and `tech()` component values that specify the format and font technology of the resource referenced by the URL. The `format()` and `tech()` components are a comma-separated list of strings of known [font formats](#font_formats) and technologies. If a user agent doesn't support the font technology or formats, it skips downloading the font resource. If no format or technology hints are supplied, the font resource is always downloaded. + +- `format()` + - : An optional declaration that follows the `url()` value that provides a hint for the user agent on the font format. + If the value is not supported or invalid, the browser may not download the resource, potentially saving bandwidth. + If omitted, the browser will download the resource and then detect the format. + If including a font source for backward-compatibility that is not in the list of [defined keywords](#formal-syntax), enclose the format string in quotes. + Possible values are described in the [Font formats](#font_formats) section below. +- `tech()` {{Experimental_inline}} + - : An optional declaration that follows the `url()` value that provides a hint for the user agent on the font technology. + The value for `tech()` may be one of the keywords described in [Font technologies](#font-technologies). +- `local()` + - : Specifies the font name should the font be available on the user's device. + Enclosing the font name in quotes is optional. - `` - - : Specifies the full name or postscript name of a locally-installed font face using the `local()` function, which uniquely identifies a single font face within a larger family. The name can optionally be enclosed in quotes. + - : Specifies the full name or postscript name of a locally-installed font face using the `local()` component value, which uniquely identifies a single font face within a larger family. + The name can optionally be enclosed in quotes. The font face name [is not case-sensitive](https://w3c.github.io/csswg-drafts/css-fonts-3/#font-family-casing). > **Note:** The {{domxref("Local Font Access API", "Local Font Access API", "", "nocode")}} can be used to access the user's locally installed font data — this includes higher-level details such as names, styles, and families, as well as the raw bytes of the underlying font files. ## Description -The value of this descriptor is a prioritized, comma-separated list of external references or locally-installed font face names. When a font is needed the {{glossary("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. +The value of this descriptor is a prioritized, comma-separated list of external references or locally-installed font face names, where each resource is specified using `url()` or `local()`. +When a font is needed, the {{glossary("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. + +If multiple `src` descriptors are set, only the last declared rule that is able to load a resource is applied. +If the last `src` descriptor can load a resource and doesn't include a `local()` font, the browser may download external font files and ignore the local version even if there is one available on the device. + +> **Note:** Values within descriptors that the browser considers invalid are ignored. +> Some browsers will ignore the whole descriptor if any item is invalid, even if only one item is invalid. +> This may affect design of fallbacks. +> See [Browser compatibility](#browser_compatibility) for more information. As with other URLs in CSS, the URL may be relative, in which case it is resolved relative to the location of the style sheet containing the `@font-face` rule. In the case of SVG fonts, the URL points to an element within a document containing SVG font definitions. If the element reference is omitted, a reference to the first defined font is implied. Similarly, font container formats that can contain more than one font load only one of the fonts for a given `@font-face` rule. Fragment identifiers are used to indicate which font to load. If a container format lacks a defined fragment identifier scheme, a simple 1-based indexing scheme (e.g., "font-collection#1" for the first font, "font-collection#2" for the second font, etc.) is used. +If the font file is a container for multiple fonts, a fragment identifier is included to indicate the sub-font that should be used, as shown below: + +```css +/* WhichFont is the PostScript name of a font in the font file */ +src: url(collection.otc#WhichFont); +/* WhichFont is the element id of a font in the SVG Font file */ +src: url(fonts.svg#WhichFont); +``` + +### Font formats + +The following table shows the valid font keywords and their corresponding font formats. +To check if a font format is supported by a browser within CSS, use the {{cssxref("@supports", "@supports")}} rule. + +| Keyword | Font Format | Common extensions | +| ------------------- | --------------------- | ----------------- | +| `collection` | OpenType Collection | .otc, .ttc | +| `embedded-opentype` | Embedded OpenType | .eot | +| `opentype` | OpenType | .otf, .ttf | +| `svg` | SVG Font (deprecated) | .svg, .svgz | +| `truetype` | TrueType | .ttf | +| `woff` | WOFF 1.0 | .woff | +| `woff2` | WOFF 2.0 | .woff2 | + +> **Note:** +> +> - `format(svg)` stands for [SVG fonts](/en-US/docs/Web/SVG/Tutorial/SVG_fonts), and `tech(color-SVG)` stands for [OpenType fonts with SVG table](https://learn.microsoft.com/en-us/typography/opentype/spec/svg) (also called OpenType-SVG color fonts), which are completely different. +> - The `opentype` and `truetype` values are equivalent whether the font file uses cubic bezier curves (within CFF/CFF2 table) or quadratic bezier curves (within glyph table). + +Older non-normalized `format()` values have the following equivalent syntax; provided as a string enclosed in quotes for backward-compatibility reasons: + +| Old syntax | Equivalent syntax | +| ------------------------------- | ----------------------------------- | +| `format("woff2-variations")` | `format(woff2) tech(variations)` | +| `format("woff-variations")` | `format(woff) tech(variations)` | +| `format("opentype-variations")` | `format(opentype) tech(variations)` | +| `format("truetype-variations")` | `format(truetype) tech(variations)` | + +### Font technologies + +The following table shows valid values for the `tech()` descriptor and their corresponding font technologies. +To check if a font technology is supported by a browser within CSS, use the {{cssxref("@supports", "@supports")}} at-rule. + +| Keyword | Description | +| :------------------ | :-------------------------------------------------------------------------------------------- | +| `color-cbdt` | Color bitmap data tables | +| `color-colrv0` | Multi-colored glyphs via COLR version 0 table | +| `color-colrv1` | Multi-colored glyphs via COLR version 1 table | +| `color-sbix` | Standard bitmap graphics tables | +| `color-svg` | SVG multi-colored tables | +| `features-aat` | TrueType `morx` and `kerx` tables | +| `features-graphite` | Graphite features, namely `Silf`, `Glat` , `Gloc` , `Feat`, and `Sill` tables | +| `features-opentype` | OpenType `GSUB` and `GPOS` tables | +| `incremental` | Incremental font loading | +| `palettes` | Font palettes by means of `font-palette` to select one of many color palettes in the font | +| `variations` | Font variations in TrueType and OpenType fonts to control the font axis, weight, glyphs, etc. | + ## Formal definition {{cssinfo}} @@ -59,38 +152,124 @@ As with other URLs in CSS, the URL may be relative, in which case it is resolved ## Formal syntax ``` -[ [ format( # ) ]? | local( ) ]# + [ format()]? [ tech( #)]? | local() + += [ | collection | embedded-opentype | opentype + | svg | truetype | woff | woff2 ] + += [ | + | variations | palettes | incremental ] + += [feature-opentype | feature-aat | feature-graphite] - = - | - + += [color-COLRv0 | color-COLRv1 | color-SVG | color-sbix | color-CBDT ] ``` ## Examples ### Specifying font resources using url() and local() +The example below shows how to define two font faces with the same font family. The `font-family` is named `MainText`. The first font face has a regular font, and the second one is a bold version of the same font family. + ```css -/* a regular font face: */ +/* Defining a regular font face */ @font-face { - font-family: examplefont; - src: local(Example Font), - url('examplefont.woff') format("woff"), - url('examplefont.otf') format("opentype"); - format("opentype"); + font-family: MainText; + src: local(Futura-Medium), + url('FuturaMedium.woff') format("woff"), + url('FuturaMedium.otf') format("opentype"); + format("opentype"); } -/* a bold font face of the same family: */ +/* Defining a different bold font face for the same family */ @font-face { - font-family: examplefont; -src: local(Example Font Bold), /* full font name */ - local(Example Font-Bold), /* postscript name */ - url('examplefont.woff') format("woff"), - url('examplefont.otf') format("opentype"); - url("examplefont.woff") format("woff"), - url("examplefont.otf") format("opentype"); + font-family: MainText; + src: local(Gill Sans Bold), /* full font name */ + local(GillSans-Bold), /* postscript name */ + url('GillSansBold.woff') format("woff"), + url('GillSansBold.otf') format("opentype"), + url("GillSansBold.svg#MyFontBold"); /* Referencing an SVG font fragment by id */ font-weight: bold; } + +/* Using the regular font face */ +p { + font-family: MainText; +} + +/* Font-family is inherited, but bold fonts are used */ +p.bold { + font-weight: bold; +} +``` + +### Specifying font resources using tech and format values + +The following example shows how to use the `tech()` and `format()` values to specify font resources. +A font using `color-colrv1` technology and `opentype` format is specified using the `tech()` and `format()` values. +A color font will be activated if the user agent supports it, and an `opentype` non-color is provided as a fallback. + +```css +@font-face { + font-family: "Trickster"; + src: url("trickster-COLRv1.otf") format(opentype) tech(color-COLRv1), url("trickster-outline.otf") + format(opentype); +} + +/* Using the font face */ +p { + font-family: "Trickster"; +} +``` + +### Fallbacks for older browsers + +Browsers should use a `@font-face` with a single `src` descriptor listing possible sources for the font. +Since the browser will use the first resource that it is able to load, items should be specified in the order that you'd most like them to be used. + +Generally this means that local files should appear before remote files, and that resources with `format()` or `tech()` constraints should appear before resources that don't have them (otherwise the less-constrained version would always be selected). +For example: + +```css +@font-face { + font-family: "MgOpenModernaBold"; + src: url("MgOpenModernaBoldIncr.otf") format("opentype") tech(incremental), url("MgOpenModernaBold.otf") + format(opentype); +} +``` + +A browser that does not support `tech()` above should ignore the first item and attempt to load the second resource. + +Some browsers do not yet [ignore invalid items](#browser_compatibility), and instead fail the whole `src` descriptor if any value is invalid. +If working with these browsers you can specify multiple `src` descriptors as fallbacks. +Note that multiple `src` descriptors are attempted in reverse-order, so at the end we have our normal descriptor with all the items. + +```css +@font-face { + font-family: "MgOpenModernaBold"; + src: url("MgOpenModernaBold.otf") format(opentype); + src: url("MgOpenModernaBoldIncr.otf") format("opentype") tech(incremental); + src: url("MgOpenModernaBoldIncr.otf") format("opentype") tech(incremental), url("MgOpenModernaBold.otf") + format(opentype); +} +``` + +### Checking if the user agent supports a font + +The following example shows how to check if the user agent supports a font technology using the {{cssxref("@supports")}} rule. +The block of CSS inside `@supports` will be applied if the user agent supports `color-COLRv1` technology. + +```css +@supports font-tech(color-COLRv1) { + @font-face { + font-family: "Trickster"; + src: url("trickster-COLRv1.otf") format(opentype) tech(color-COLRv1); + } + + .colored_text { + font-family: "Trickster"; + } +} ``` ## Specifications @@ -103,6 +282,8 @@ src: local(Example Font Bold), /* full font name */ ## See also +- {{cssxref("@font-face", "@font-face")}} +- {{cssxref("@supports", "@supports")}} - {{cssxref("@font-face/font-display", "font-display")}} - {{cssxref("@font-face/font-family", "font-family")}} - {{cssxref("@font-face/font-stretch", "font-stretch")}}