CSS @font-feature-values At-Rule

CSS @font-feature-values At-Rule

The @font-feature-values at-rule defines custom names for alternate characters and other typographic features available in OpenType fonts. These names can then be used with the font-variant-alternates property to select specific font features without repeatedly using numeric feature indexes.

@font-feature-values Syntax

@font-feature-values "Example Font" {
  @styleset {
    alternate-style: 1;
  }
}
.heading {
  font-family: "Example Font", serif;
  font-variant-alternates: styleset(alternate-style);
}

The at-rule begins with @font-feature-values, followed by a font family name and a block containing one or more feature value definitions.

In this example, alternate-style is a custom name for OpenType stylistic set ss01. The styleset() function uses that name to request the alternate characters.

The selected font must provide the requested feature for the appearance of the text to change.

How @font-feature-values Works

OpenType fonts can contain alternate versions of letters, numbers, and symbols. These alternatives are identified by font-specific feature tags and indexes.

The @font-feature-values at-rule associates readable names with those indexes for a particular font family.

@font-feature-values "Display Font" {
  @swash {
    decorative: 2;
  }
}
.title {
  font-family: "Display Font", cursive;
  font-variant-alternates: swash(decorative);
}

The name decorative refers to swash alternate number 2 in the specified font. When the font supports that alternate, the browser can display the corresponding decorative glyphs.

Defining a name does not activate the feature by itself. The feature must also be requested through font-variant-alternates.

Feature Value Blocks

The @font-feature-values at-rule supports several nested at-rules for naming different OpenType features.

Each nested at-rule contains declarations that associate a custom feature name with one or more numeric indexes.

Defining Several Features

@font-feature-values "Example Font" {
  @stylistic {
    alternate-letters: 1;
  }
  @styleset {
    modern-style: 2;
  }
  @swash {
    decorative: 1;
  }
  @character-variant {
    alternate-a: 3 2;
  }
}

These declarations define four named features for the same font family. The alternate-a definition requests value 2 of character variant cv03.

The numbers depend on the features provided by the font. A value that works with one font may produce a different result or no change with another.

Using Named Font Features

The font-variant-alternates property activates features defined by @font-feature-values.

@font-feature-values "Example Font" {
  @styleset {
    heading-style: 1;
  }
  @swash {
    fancy-ending: 2;
  }
}
h1 {
  font-family: "Example Font", serif;
  font-variant-alternates: styleset(heading-style);
}
.decorative-heading {
  font-family: "Example Font", serif;
  font-variant-alternates: styleset(heading-style) swash(fancy-ending);
}

The first rule requests the named stylistic set. The second requests both the stylistic set and the swash alternate.

Multiple alternate features can be requested together when the font provides them. The actual appearance depends on the font's OpenType tables and the characters being displayed.

Multiple Font Families

The same custom feature name can be defined for different font families, even when those fonts use different numeric indexes.

@font-feature-values "Font One" {
  @styleset {
    alternate-heading: 1;
  }
}
@font-feature-values "Font Two" {
  @styleset {
    alternate-heading: 4;
  }
}
.heading {
  font-family: "Font One", "Font Two", serif;
  font-variant-alternates: styleset(alternate-heading);
}

The browser uses the feature mapping associated with the font family selected for the text. This makes it possible to use one descriptive feature name across multiple fonts.

A single @font-feature-values rule can also list multiple font families separated by commas when they share the same feature indexes.

@font-feature-values "Font One", "Font Two" {
  @styleset {
    alternate-heading: 1;
  }
}

This form is appropriate only when both fonts use the same numeric index for the intended feature.

Font Requirements

Named font features work only when the selected font contains the corresponding OpenType features.

For example, defining @swash does not add decorative characters to a font that does not contain swash alternates.

Before using custom feature names, check the font's documentation for supported stylistic sets, character variants, swashes, and other alternates.

The @font-feature-values at-rule does not load a font file. Use @font-face when a downloadable font must be defined.

@font-face {
  font-family: "Example Font";
  src: url("fonts/example-font.woff2") format("woff2");
}
@font-feature-values "Example Font" {
  @styleset {
    alternate-style: 1;
  }
}

The font file in this example is a placeholder. Replace it with an actual font that supports stylistic set ss01.

@font-feature-values Example

The following example defines a named stylistic set and applies it to a heading.

@font-face {
  font-family: "Display Font";
  src: url("fonts/display-font.woff2") format("woff2");
  font-display: swap;
}
@font-feature-values "Display Font" {
  @styleset {
    special-heading: 1;
  }
}
h2 {
  font-family: "Display Font", Georgia, serif;
  font-variant-alternates: styleset(special-heading);
}

If the font includes stylistic set ss01, the heading can display its alternate letterforms. If the font does not provide the requested feature, the text retains its normal glyphs.

This example is provided as code because a meaningful visual comparison requires a specific font file with documented OpenType alternates.

Browser Support

The @font-feature-values at-rule is widely available in modern browsers. The appearance of alternate glyphs depends on the font and support for the associated font-variant-alternates features. Visit Can I Use? and search for CSS font feature values for compatibility information.

Specifications

The @font-feature-values at-rule is defined in CSS Fonts Module Level 4. The specification describes how custom feature names are associated with font-specific OpenType feature indexes.

CSS Fonts Module Level 4