CSS font-variant-ligatures Property

The CSS font-variant-ligatures property controls which ligatures and contextual forms a font uses. A ligature is a single glyph that a typeface substitutes for two or more characters that would otherwise collide or look awkward when placed side by side — the classic example is the fi pair, where the dot of the i clashes with the hook of the f.

Ligatures are an OpenType feature baked into the font file. This property simply lets you turn the available ones on or off; if the font does not contain a particular ligature, the property has no visible effect. Because of that, font-variant-ligatures only changes appearance, never the underlying text — copy, search, and screen readers still see the original characters.

font-variant-ligatures accepts one keyword from each of the following groups (combined in any order):

normal — let the font decide (the default).
none — turn off every ligature and contextual form.
<common-lig-values> — common-ligatures / no-common-ligatures
<discretionary-lig-values> — discretionary-ligatures / no-discretionary-ligatures
<historical-lig-values> — historical-ligatures / no-historical-ligatures
<contextual-alt-values> — contextual / no-contextual

Initial Value	normal
Applies to	All elements. It also applies to ::first-letter and ::first-line.
Inherited	Yes.
Animatable	No.
Version	CSS3
DOM Syntax	object.style.fontVariantLigatures = "normal";

Syntax

font-variant-ligatures: normal | none | <common-lig-values> | <discretionary-lig-values> | <historical-lig-values> | <contextual-alt-values>;

You can list one keyword from several groups together. For example, this keeps common ligatures but enables decorative ones and turns off contextual joining:

font-variant-ligatures: common-ligatures discretionary-ligatures no-contextual;

Example of the font-variant-ligatures property

The two spans below render the same characters with the same font. The first disables common ligatures, so f and i sit as two separate glyphs; the second enables them, so the pair joins into one fi glyph.

<!DOCTYPE html>
<html>
  <head>
    <title>The title of the document </title>
    <style>
      div {
        font-family: Lora, serif;
        font-size: 35vw;
      }
      .gray {
        font-variant-ligatures: no-common-ligatures;
        color: #ccc;
      }
      .blue {
        font-variant-ligatures: common-ligatures;
        color: #1c87c9;
      }
    </style>
  </head>
  <body>
    <h2>Font-variant-ligatures property example</h2>
    <div>
      <span class="gray">fi</span>
      <span class="blue">fi</span>
    </div>
  </body>
</html>

Try it Yourself »

Result

![CSS font-variant-ligatures Property](/uploads/media/default/0001/03/fc947bebf8b5cb8a0a41ea56ea12d1fd303a936c.png "fi rendered with and without common ligatures" width="420" height="200")

Types of ligatures

CSS recognizes four families of ligatures and contextual forms, all aligned with the widely used OpenType format. Each family has its own keyword pair, so you can toggle them independently.

Common ligatures

Common ligatures fire when two characters would otherwise "hit" each other — the lowercase f + i pair is the textbook case. Joining them keeps the text comfortable to read, so most fonts and browsers enable common ligatures by default. Toggle them explicitly with:

/* Enable common ligatures (the default) */
font-variant-ligatures: common-ligatures;

/* Disable common ligatures */
font-variant-ligatures: no-common-ligatures;

Discretionary ligatures

Discretionary ligatures (also called decorative ligatures) exist for visual flourish rather than readability — think of an ornate ct or st join in a display typeface. They are off by default, so you opt in only where you want the decoration:

/* Enable discretionary ligatures */
font-variant-ligatures: discretionary-ligatures;

/* Disable discretionary ligatures */
font-variant-ligatures: no-discretionary-ligatures;

Historical ligatures

Historical ligatures reproduce forms once common in old books and manuscripts, such as the long-s (ſ) combinations. Like discretionary ligatures, they are decorative and off by default:

/* Enable historical ligatures */
font-variant-ligatures: historical-ligatures;

/* Disable historical ligatures */
font-variant-ligatures: no-historical-ligatures;

Contextual alternates

Contextual alternates improve legibility by choosing a glyph that joins smoothly to its neighbours. They are most noticeable in connected scripts (handwriting fonts, Arabic), where strokes must flow continuously from one character to the next. Toggle them with:

/* Enable contextual alternates */
font-variant-ligatures: contextual;

/* Disable contextual alternates */
font-variant-ligatures: no-contextual;

Values

Value	Description
normal	Activation of forms and ligatures depends on the font, language and the kind of script. This is the default value of this property.
none	All the ligatures and contextual forms are disabled.
`<common-lig-values>`	Controls all the ligatures.
`<discretionary-lig-values>`	Controls specific ligatures.
`<historical-lig-values>`	Controls ligatures that are used in old books.
`<contextual-alt-values>`	Controls the adaptation of the letters to their context (`contextual` / `no-contextual`).
initial	Sets the property to its default value (`normal`).
inherit	Inherits the property from the parent element.

When to use it

Most of the time normal is the right choice — the font's designer already picked sensible defaults. Reach for explicit values when:

A display or logo heading needs decorative discretionary-ligatures it would not get otherwise.
A monospace / code block renders ligatures you do not want (some editors turn != into a single glyph); none or no-common-ligatures restores literal characters.
You set text-rendering: optimizeSpeed or animate text, and ligature substitution causes shimmering — disabling it can steady the render.

font-variant — the shorthand that bundles ligatures with caps, numeric, and other variant features.
font-feature-settings — low-level access to the same OpenType features by their four-letter tags (liga, dlig, hlig, calt).
font-kerning — controls spacing between glyph pairs, the feature most often confused with ligatures.
css-font-variant-caps-property and css-font-variant-numeric-property — sibling font-variant-* longhands.

Practice

What does the CSS 'font-variant-ligatures' property control?

It controls how characters are spacedIt controls the capitalization of textIt controls how ligatures in the text are displayedIt controls text wrap settingsIt controls the typeface of the text