CSS @character-variant At-Rule

CSS @character-variant At-Rule

The @character-variant at-rule assigns readable names to character-variant features in an OpenType font. It is nested inside @font-feature-values and allows those names to be used with the font-variant-alternates property.

@character-variant Syntax

@font-feature-values FontFamily {
  @character-variant {
    custom-name: feature-index;
  }
}

The @character-variant block contains one or more named declarations. Each declaration maps a custom name to a numeric OpenType character-variant feature value.

A declaration can contain one or two integers. The first selects the character-variant feature, and the optional second selects a specific alternate within that feature.

How @character-variant Works

OpenType fonts can include alternate versions of certain characters. Character-variant features are identified by tags such as cv01, cv02, and cv03.

The @character-variant at-rule gives these numbered features meaningful CSS names. Instead of referring to a feature number directly when styling text, you can use the name defined in the at-rule.

The font must contain the corresponding OpenType feature for the character appearance to change. The at-rule does not create new glyphs or add features to a font.

Feature Values

The first integer identifies a character-variant feature. For example, 1 corresponds to cv01, while 2 corresponds to cv02.

@font-feature-values "Example Font" {
  @character-variant {
    alternate-a: 1;
    alternate-b: 2;
    alternate-c: 3 2;
  }
}

In this example, alternate-a selects cv01, alternate-b selects cv02, and alternate-c selects the second alternate associated with cv03.

The names are chosen by the stylesheet author. The feature numbers must match the capabilities of the selected font.

Using font-variant-alternates

After defining a named character variant, use the character-variant() function in the font-variant-alternates property to activate it.

@font-feature-values "Example Font" {
  @character-variant {
    alternate-a: 1;
  }
}
.example {
  font-family: "Example Font", serif;
  font-variant-alternates: character-variant(alternate-a);
}

The browser looks for the named definition associated with the selected font family and attempts to apply the corresponding OpenType feature.

If the font does not provide that feature, the text generally retains its normal character forms.

@character-variant Example

The following example defines a name for the first OpenType character-variant feature and applies it to a paragraph.

@font-feature-values "Example Font" {
  @character-variant {
    alternate-letters: 1;
  }
}
.variant-text {
  font-family: "Example Font", serif;
  font-variant-alternates: character-variant(alternate-letters);
}

The example requires a font named Example Font that supports the cv01 feature. Replace the placeholder family name with an installed or loaded font that provides the feature.

Browser Support

Support for named character variants depends on the browser's implementation of @font-feature-values, font-variant-alternates, and the font's available OpenType features. For current compatibility, visit Can I Use? and search for font variant alternates.

Specifications

The @character-variant at-rule is defined in the CSS Fonts Module Level 4 specification as part of the @font-feature-values syntax.

CSS Fonts Module Level 4