CSS @font-feature-values Rule
The @font-feature-values at-rule uses a name for features in the font-variant-alternates property. Read about the property values and see examples.
The @font-feature-values at-rule lets you assign a human-readable name to a numeric OpenType feature index, so you can refer to a font's alternate glyphs by name instead of by raw number when you use the font-variant-alternates property.
This page explains what problem the rule solves, its syntax, the feature blocks it accepts, and a complete working example.
Why it exists
Many OpenType fonts ship with alternate glyphs in addition to each character's default shape — swashes (decorative flourishes), ornaments, stylistic alternates, historical forms, and so on. Inside the font, each alternate is identified only by a number (an index). Without this at-rule you would have to remember that, say, "the fancy swash is index 1" and hard-code that number everywhere.
@font-feature-values lets you write that mapping once, give the index a name like fancy, and then call swash(fancy) in your CSS. The name applies per font family, so two different fonts can each define their own fancy swash pointing at different indexes.
Two things to keep in mind:
- It works exclusively with
font-variant-alternates— it has no effect on any other property. - It only does something if the matching font is actually loaded and that font contains the referenced alternate glyphs. If you need to toggle low-level OpenType features by their four-letter tag instead, use
font-feature-settings.
It can be placed at the top level of a stylesheet or inside a conditional-group at-rule such as @media.
Feature blocks
The at-rule body may contain any of these named blocks, each mapping a name to an index:
@swash@annotation@ornaments@stylistic@styleset@character-variant
Each block name lines up with the matching functional notation on font-variant-alternates (a @swash name is used by swash(), an @ornaments name by ornaments(), and so on).
Syntax
Syntax of CSS @font-feature-values At-rule
@font-feature-values <family-name> {
@swash { name: index; }
@annotation { name: index; }
@ornaments { name: index; }
@stylistic { name: index; }
@styleset { name: index; }
@character-variant { name: index; }
}Example of the @font-feature-values at-rule:
Example of CSS @font-feature-values At-rule
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
<style>
@font-feature-values "Leitura Display Swashes" {
@swash {
fancy: 1;
}
}
p {
font-size: 1.5rem;
}
.variant {
font-family: Leitura Display Swashes;
font-variant-alternates: swash(fancy);
}
</style>
</head>
<body>
<h2>@Font-feature-values at-rule example</h2>
<p>
The font-variant-alternates CSS property controls the usage of alternate glyphs. These alternate glyphs may be referenced by alternative names defined in @font-feature-values.
</p>
<p>This property is supported by Firefox and Safari.</p>
<p class="variant">This property is supported by Firefox and Safari.</p>
</body>
</html>Here, @swash { fancy: 1; } names index 1 of the Leitura Display Swashes font as fancy. The .variant paragraph then activates that alternate with font-variant-alternates: swash(fancy). Because the named font is not loaded in this snippet, the text falls back to a default font and the swashes will not render — the point of the example is the wiring, not the visual result. Swap in a font you actually have via @font-face to see the alternates.
Browser support
@font-feature-values is supported in Firefox, Safari, and Chrome/Edge (Chromium added support in version 128, August 2024). Internet Explorer never supported it. Because alternate glyphs are purely decorative, treating them as a progressive enhancement is safe: browsers and fonts that lack the feature simply show the default glyph.
Values
| Value | Description |
|---|---|
| @swash | Specifies a feature name that works with the swash() functional notation of font-variant-alternates. |
| @annotation | Specifies a feature name that works with the annotation() functional notation of font-variant-alternates. |
| @ornaments | Specifies a feature name that works with the ornaments() functional notation of font-variant-alternates. |
| @stylistic | Specifies a feature name that works with the stylistic() functional notation of font-variant-alternates. |
| @styleset | Specifies a feature name that works with the styleset() functional notation of font-variant-alternates. |
| @character-variant | Specifies a feature name that works with the character-variant() functional notation of font-variant-alternates. |