Font fallbacks¶

When EPPlus measures, shapes or renders text, the fonts used in the workbook are not always available on the machine running the code, and an available font does not always contain every character in the text. EPPlus handles both cases with built-in fallbacks at three levels:

In addition, the HTML and SVG exports substitute Office cloud fonts with fonts that browsers have, and text measurement can use serialized font metrics when a font is missing.

The defaults are designed so that you don't need to configure anything. To change them, see Configure fonts.

Font-level fallback¶

When text uses a font, EPPlus resolves it in this order:

1. The requested font. The font is searched for in the configured font directories and, unless SearchSystemDirectories is turned off, the operating system's font directories. The match must be exact: the same family and the same style. A request for Calibri Bold is not satisfied by Calibri Regular.
2. Your own fallback chain for the font name, if you have configured one in FontFallbacks.
3. The built-in fallback chain for the font name, if there is one (see the table below).
4. Archivo Narrow, a last-resort font that is embedded in EPPlus and is always available.

Every font in a chain must also be an exact match, family and style, to be used. If no font in a chain matches, resolution continues with the next step. Your own chain is tried before the built-in one, so your choices always win.

If you supply your own FontResolver, it replaces this whole process.

Built-in fallback chains¶

The built-in chains cover common Office and system fonts. They prefer metric-compatible fonts: open-source fonts designed with the same character widths as the original, such as Carlito for Calibri, Caladea for Cambria and Arimo for Arial. With a metric-compatible substitute, text takes up the same space as with the original font, so column widths, line breaks and page layout stay the same.

These fonts are not bundled with EPPlus. They are used only if they are installed or available in one of your font directories. On Linux servers and in containers, installing the Carlito, Caladea and Liberation font packages gives you substitutes for the most common Office fonts.

To add a chain for a font that is not in the table, or to replace a built-in chain, use FontFallbacks:

package.Workbook.ConfigureFonts(cfg =>
{
    // Tried before the built-in chain for Calibri.
    cfg.FontFallbacks["Calibri"] = new[] { "Open Sans", "Arial" };
});

package.Workbook.ConfigureFonts(Sub(cfg)
                                    ' Tried before the built-in chain for Calibri.
                                    cfg.FontFallbacks("Calibri") = New String() {"Open Sans", "Arial"}
                                End Sub)

The last-resort font¶

Archivo Narrow guarantees that font resolution always ends with a font, so a missing font never causes an export to fail. It covers Latin script. Text in other writing systems is still handled by glyph-level fallback, which works on top of whichever font was resolved, including Archivo Narrow.

Script-level fallback¶

A font can be available and still lack the characters of a writing system. A typical example is a Latin font such as Calibri used for a cell that contains Japanese text. For each writing system (Unicode script), EPPlus has a fallback chain of fonts to take the missing characters from.

The built-in chains try the fonts that ship with Windows and macOS first, then the Noto fonts that are common on Linux:

A chain never crosses into another language. Japanese text does not fall back to a Chinese font, or the reverse, since the same ideograph is drawn differently in Chinese and Japanese typography.

Fonts in a script chain must be installed or available in a font directory, and are skipped if they are not. A chain is resolved the first time a character of that script is encountered.

There are no built-in chains for Latin, Cyrillic or Greek, since these are expected to be covered by the font itself. If your workbooks contain Cyrillic or Greek text in fonts that may be missing on the machine, configure a chain for those scripts.

Use SetScriptFallback to configure a chain. It replaces the built-in chain for the script completely; the two are not merged:

package.Workbook.ConfigureFonts(cfg =>
{
    cfg.FontDirectories.Add(@"C:\MyFonts");

    // Japanese text: prefer our own font, then the Windows default.
    cfg.SetScriptFallback(UnicodeScript.Hiragana, "Noto Sans JP", "Yu Gothic");
    cfg.SetScriptFallback(UnicodeScript.Katakana, "Noto Sans JP", "Yu Gothic");

    // Cyrillic has no built-in chain.
    cfg.SetScriptFallback(UnicodeScript.Cyrillic, "Noto Sans", "Arial");

    // No fallback at all for Thai: missing characters render as .notdef.
    cfg.SetScriptFallback(UnicodeScript.Thai);
});

package.Workbook.ConfigureFonts(Sub(cfg)
                                    cfg.FontDirectories.Add("C:\MyFonts")

                                    ' Japanese text: prefer our own font, then the Windows default.
                                    cfg.SetScriptFallback(UnicodeScript.Hiragana, "Noto Sans JP", "Yu Gothic")
                                    cfg.SetScriptFallback(UnicodeScript.Katakana, "Noto Sans JP", "Yu Gothic")

                                    ' Cyrillic has no built-in chain.
                                    cfg.SetScriptFallback(UnicodeScript.Cyrillic, "Noto Sans", "Arial")

                                    ' No fallback at all for Thai: missing characters render as .notdef.
                                    cfg.SetScriptFallback(UnicodeScript.Thai)
                                End Sub)

Note that Japanese text is usually a mix of Han, Hiragana and Katakana. To make all of it come from the same font, configure the same chain for all three scripts.

Glyph-level fallback¶

Fallback within a text is decided character by character. For each character, EPPlus uses the first of the following that has a glyph for it:

1. The resolved font, that is the requested font or the font chosen by font-level fallback.
2. Depending on the character:
   • Emoji: Noto Emoji, which is bundled with EPPlus.
   • Mathematical symbols: Noto Math, which is bundled with EPPlus.
   • Other characters: the script chain for the character's script.
3. If no font has the glyph, the character is drawn with the font's missing glyph symbol (.notdef), usually an empty box. The export still succeeds.

A single cell can therefore be drawn with several fonts, for example Calibri for the Latin text, Yu Gothic for the Japanese characters and Noto Emoji for an emoji. In a PDF, each font that contributed glyphs is subsetted and embedded.

Emoji and mathematical symbols are always handled by the bundled fonts and cannot be configured.

Limitations¶

• Text shaping applies to the resolved font only. Kerning, ligatures, contextual forms and the placement of diacritical marks are applied to glyphs from the resolved font, but not to glyphs taken from a fallback font. For most scripts this makes little visible difference. For scripts that depend on contextual forms, such as Arabic and Devanagari, use a font that covers the script as the cell's font rather than relying on fallback.
• Fallback glyphs are always regular. Fonts in a script chain are loaded in their regular style, so bold or italic text that falls back to another font is drawn without bold or italic.
• Variation sequences (a character followed by a variation selector, used by some emoji and CJK ideographs) are only honoured when the same font has both the character and the sequence.

Web font substitution¶

When a workbook is exported to HTML or SVG, the text is drawn by the browser, with the fonts the browser has access to. Office cloud fonts, such as Aptos, are delivered to Office through Microsoft's font service and are not installed on the system, so browsers can't use them, even on machines where Office has them.

For the HTML and SVG exports, EPPlus therefore substitutes these fonts with fonts that ship with Windows and have metric-compatible open alternatives. The text is then both measured on the server and drawn in the browser with the same font:

The substitution is a single step: the substitute is not substituted again. PDF export is not affected, since a PDF embeds the fonts it uses.

To change the substitutions, edit WebFontSubstitutions. Remove an entry to pass the original font name through to the browser, for example if your users have the font installed:

package.Workbook.ConfigureFonts(cfg =>
{
    cfg.WebFontSubstitutions["Aptos"] = "Segoe UI";
    cfg.WebFontSubstitutions.Remove("Aptos Narrow");
});

package.Workbook.ConfigureFonts(Sub(cfg)
                                    cfg.WebFontSubstitutions("Aptos") = "Segoe UI"
                                    cfg.WebFontSubstitutions.Remove("Aptos Narrow")
                                End Sub)

Measurement without the font¶

Measuring text, for example to autofit columns or to break lines, needs the widths of the characters, not their outlines. When font resolution ends at the last-resort font, EPPlus measures with serialized metrics of the requested font instead, if it has them. These are character widths for common fonts that are included in EPPlus. Measuring the right font from stored widths is closer to the result in Excel than measuring a different font exactly.

A metric-compatible substitute found by font-level fallback is always preferred, since it is a real font. The behaviour is controlled by MetricsFallback:

package.Workbook.ConfigureFonts(cfg =>
{
    // Same column widths on every server, whatever fonts are installed.
    cfg.MetricsFallback = MetricsFallbackMode.Always;
});

package.Workbook.ConfigureFonts(Sub(cfg)
                                    ' Same column widths on every server, whatever fonts are installed.
                                    cfg.MetricsFallback = MetricsFallbackMode.Always
                                End Sub)

Serialized metrics are used for measurement only. Text that is rendered, for example in a PDF, always needs a real font.

Finding out which fonts were used¶

To see which fonts and fallbacks EPPlus actually used, assign a logger to the Logger property in ConfigureFonts. The fallback decisions are reported as events:

A GlyphMissing warning includes the reason, for example that no script chain is configured for the character's script, or that none of the fonts in the chain is installed.

See also¶

• Configure fonts
• PDF
• HTML & CSS
• Autofit columns