CSS font-variant Descriptor

The CSS font-variant descriptor is used with the @font-face at-rule to define the inital settings for the font-variant property when the @font-face at-rule is rendered.

The font-variant descriptor is not to be confused with the font-variant property. The font-variant descriptor does not affect font selection. It is used solely with the @font-face at-rule to define the initial values for the font-variant property, which can then be used elsewhere in the style sheet to change these values.

Official Syntax

The font-variant descriptor has the following syntax (which is the same syntax that the font-variant property uses):

The initial value is normal.

These values are explained below. The OpenType feature tag/s are included where applicable.

For more information about these values, visit the link/s within each description.

normal

Resets all subproperties to their initial value.

none

Sets font-variant-ligatures to none and resets all other font feature properties to their initial value.

Ligatures

These are the possible values for the font-variant-ligatures property. They are grouped under common ligatures, discretionary ligatures, historical ligatures, and contextual alternates.

common-lig-values

Specifies whether common ligatures (OpenType features: liga, clig) are enabled or not. This can be one of the following values:

common-ligatures: Enables display of common ligatures. For OpenType fonts, common ligatures are enabled by default.
no-common-ligatures: Disables display of common ligatures.

discretionary-lig-values

Specifies whether discretionary ligatures (OpenType feature: dlig) are enabled or not. This can be one of the following values:

discretionary-ligatures: Enables display of discretionary ligatures. Which ligatures are discretionary or optional is decided by the type designer, so authors will need to refer to the documentation of a given font to understand which ligatures are considered discretionary.
no-discretionary-ligatures: Disables display of discretionary ligatures.

historical-lig-values

Specifies whether historical ligatures (OpenType feature: hlig) are enabled or not. This can be one of the following values:

historical-ligatures: Enables display of historical ligatures.
no-historical-ligatures: Disables display of historical ligatures.

contextual-alt-values

Specifies whether contextual alternates are enabled or not (OpenType feature: hlig). This can be one of the following values:

contextual: Enables display of contextual alternates.
no-contextual: Disables display of contextual alternates.

Alternates

These are the possible values for the font-variant-alternates property.

stylistic(feature-value-name): Enables display of stylistic alternates (font specific, OpenType feature: salt feature-index).
historical-forms: Enables display of historical forms (OpenType feature: hist).
styleset(feature-value-name #): Enables display with stylistic sets (font specific, OpenType feature: ssfeature-index). For example, ss01, ss02, ss03, etc
character-variant(feature-value-name #): Enables display of specific character variants (font specific, OpenType feature: cvfeature-index). For example, cv01, cv02, cv03, etc
swash(feature-value-name): Enables display of swash glyphs (font specific, OpenType feature: swsh feature-index, cswh feature-index).
ornaments(feature-value-name): Enables replacement of default glyphs with ornaments, if provided in the font (font specific, OpenType feature: ornm feature-index).
annotation(feature-value-name): Enables display of alternate annotation forms (font specific, OpenType feature: nalt feature-index).

Caps

These are the possible values for the font-variant-caps property.

small-caps

Specifies that the font is rendered in small-caps (OpenType feature: smcp). Small caps typically appear as uppercase letters but in the size of lower case letters.

all-small-caps

Enables display of small capitals for both upper and lowercase letters (OpenType features: c2sc, smcp).

With normal small caps, any uppercase character is rendered at full uppercase size, while lowercase characters are rendered smaller. However, when the all-small-caps keyword is used, those uppercase characters are rendered at the smaller size.

petite-caps

Enables display of petite capitals (OpenType feature: pcap).

If the font doesn't support petite capitals, the property behaves as though small-caps had been specified instead.

all-petite-caps

Enables display of petite capitals for both upper and lowercase letters (OpenType features: c2pc, pcap).

If this keyword is used on a font that doesn't support this feature, the property behaves as though all-small-caps had been specified instead.

unicase

Enables display of mixture of small capitals for uppercase letters with normal lowercase letters (OpenType feature: unic).

titling-caps

Enables display of titling capitals (OpenType feature: titl).

Titling capitals are a variant of uppercase designed for heading and titles. The stroke width is reduced for use at larger point sizes where the stroke weight used in smaller text sizes would be too heavy.

If this is used on a font that doesn't support this feature, the property has no visible effect.

Numeric

These are the possible values for the font-variant-numeric property.

numeric-figure-values

This can be one of the following values:

lining-nums: Enables display of lining numerals (OpenType feature: lnum).
oldstyle-nums: Enables display of old-style numerals (OpenType feature: onum).

numeric-spacing-values

This can be one of the following values:

proportional-nums: Enables display of proportional numerals (OpenType feature: pnum).
tabular-nums: Enables display of tabular numerals (OpenType feature: tnum).

numeric-fraction-values

This can be one of the following values:

diagonal-fractions: Enables display of lining diagonal fractions (OpenType feature: frac).
stacked-fractions: Enables display of lining stacked fractions (OpenType feature: afrc).

ordinal

Enables display of letter forms used with ordinal numbers (OpenType feature: ordn).

slashed-zero

Enables display of slashed zeros (OpenType feature: zero).

East Asian

These are the possible values for the font-variant-east-asian property.

east-asian-variant-values

This can be one of the following values:

normal: None of the features listed below are enabled.
jis78: Enables rendering of JIS78 forms (OpenType feature: jp78).
jis83: Enables rendering of JIS83 forms (OpenType feature: jis83).
jis90: Enables rendering of JIS90 forms (OpenType feature: jis90).
jis04: Enables rendering of JIS04 forms (OpenType feature: jis04).
simplified: Enables rendering of simplified forms (OpenType feature: smpl).
traditional: Enables rendering of traditional forms (OpenType feature: trad).

east-asian-width-values

This can be one of the following values:

full-width: Enables rendering of full-width variants (OpenType feature: fwid).
proportional-width: Enables rendering of proportionally-spaced variants (OpenType feature: pwid).

ruby

Enables display of ruby variant glyphs (OpenType feature: ruby).

Official Specifications

The font-variant descriptor is defined in CSS Fonts Module Level 3 (W3C Candidate Recommendation 3 October 2013).