CSS font-variant-ligatures Property

Description

The font-variant-ligatures CSS property controls whether and how a font’s built-in ligatures and related glyph substitutions are applied when text is shaped for display. Ligatures are glyph-level combinations or alternative forms created by a type designer to improve spacing, readability, or aesthetics (for example, common Latin ligatures that join characters like "f" and "i"). Beyond simple joined characters, modern fonts can provide contextual substitutions, discretionary or historical forms, and script-specific shaping rules; this property is the author-facing switch that tells the browser’s shaping engine which of those designer-provided substitutions to honor.

Availability and effect of those substitutions depend primarily on the typeface itself and the shaping engine. A given font file supplies the glyphs and OpenType features that make ligatures and substitutions possible, so the visual result will vary with which font you specify via font-family. For finer-grained control than this property provides, authors can use lower-level feature toggles exposed by the platform, for example font-feature-settings. The ligature setting is also one axis of behavior folded into broader typographic controls — it interacts with the family-level and variant-level choices you can make with properties such as font-variant.

When deciding whether to rely on or change ligature behavior, consider legibility, aesthetics, and context. In running body text, many typographers prefer certain ligatures because they can reduce awkward collisions and produce smoother word shapes; in tightly spaced or small-size text, however, some discretionary ligatures can harm readability. For technical content, code samples, tabular numbers, or settings where precise character alignment matters, designers often choose to suppress font-provided substitutions to keep each character visually and semantically distinct. From an accessibility standpoint, ligatures are a visual shaping feature — underlying text, copy/paste behavior, and assistive technology output are generally unchanged — but you should still test with real content and fonts to confirm the desired result. Finally, since ligature handling is performed by the text shaping pipeline, enabling or disabling complex feature sets can slightly alter layout and rendering work, so test across target platforms to ensure consistent appearance.

Definition

Initial value: normal
Applies to: All elements
Inherited: Yes
Computed value: As specified
Animatable: No
JavaScript syntax: object.style.fontVariantLigatures

Interactive Demo

font-variant-ligatures: normal;

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

font-variant-ligatures: common-ligatures;

Difficult waffles

Syntax

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

Values

normalA value of 'normal' specifies that common default features are enabled. For OpenType fonts, common ligatures and contextual forms are on by default, discretionary and historical ligatures are not.
noneSpecifies that all types of ligatures and contextual forms covered by this property are explicitly disabled. In situations where ligatures are not considered necessary, this may improve the speed of text rendering.
<common-lig-values> = [ common-ligatures | no-common-ligatures ]common-ligatures - Enables display of common ligatures (OpenType features: liga, clig). For OpenType fonts, common ligatures are enabled by default.
no-common-ligatures - Disables display of common ligatures (OpenType features: liga, clig).
<discretionary-lig-values> = [ discretionary-ligatures | no-discretionary-ligatures ]discretionary-ligatures - Enables display of discretionary ligatures (OpenType feature: dlig). 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 (OpenType feature: dlig).
<historical-lig-values> = [ historical-ligatures | no-historical-ligatures ]historical-ligatures - Enables display of historical ligatures (OpenType feature: hlig).
no-historical-ligatures - Disables display of historical ligatures (OpenType feature: hlig).
<contextual-alt-values> = [ contextual | no-contextual ]contextual - Enables display of contextual alternates (OpenType feature: calt). Although not strictly a ligature feature, like ligatures this feature is commonly used to harmonize the shapes of glyphs with the surrounding context. For OpenType fonts, this feature is on by default.
no-contextual - Disables display of contextual alternates (OpenType feature: calt).

Example

HTML

<div class='demo'>

  <h1>font-variant-ligatures examples</h1>

  <div class='grid'>

    <div class='card'>

      <h2>Default (browser)</h2>

      <p class='sample default'>office efficient afflict fluffy flow stiff coffee affinity</p>

    </div>



    <div class='card'>

      <h2>font-variant-ligatures: none</h2>

      <p class='sample none'>office efficient afflict fluffy flow stiff coffee affinity</p>

    </div>



    <div class='card'>

      <h2>font-variant-ligatures: common-ligatures</h2>

      <p class='sample common'>office efficient afflict fluffy flow stiff coffee affinity</p>

    </div>



    <div class='card'>

      <h2>combined (discretionary + historical)</h2>

      <p class='sample combined'>stitch aesthetic longstitch ashfield artist</p>

    </div>

  </div>

</div>

CSS

/* Basic layout and type */
body {
  margin: 24px;
  font-family: Georgia, 'Times New Roman', serif;
  background: #f7f7fb;
  color: #111;
}

.demo h1 {
  margin: 0 0 18px 0;
  font-size: 20px;
}

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
  gap: 18px;
}

.card {
  background: #fff;
  padding: 14px;
  border-radius: 8px;
  box-shadow: 0 1px 4px rgba(16, 24, 40, 0.06);
  border: 1px solid rgba(16, 24, 40, 0.04);
}

.card h2 {
  margin: 0 0 8px 0;
  font-size: 14px;
  color: #333;
}

.sample {
  margin: 0;
  font-size: 20px;
  line-height: 1.4;
  color: #111;
}

/* Examples of font-variant-ligatures */
.sample.default {
  /* browser default; typically common ligatures enabled */
  font-variant-ligatures: normal;
}

.sample.none {
  /* disable all ligatures */
  font-variant-ligatures: none;
}

.sample.common {
  /* explicitly enable only common (standard) ligatures */
  font-variant-ligatures: common-ligatures;
}

.sample.combined {
  /* enable several kinds of discretionary/historical/contextual ligatures if the font provides them */
  font-variant-ligatures: common-ligatures discretionary-ligatures historical-ligatures contextual;
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS font-variant-ligatures property. Hover over a browser icon to see the version that first introduced support for this CSS property.