Recursive AI

Shape text with font fallback in C#

onefont is a free, open-source font and text-shaping library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Font fallback selects another font when the preferred face lacks a character.

Terminal
dotnet add package RecursiveAI.OneFont

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

Both Noto subset fonts below are in the zip under the SIL Open Font License.

C#
using OneFont;
 
var latin = FontFace.Load(
    File.ReadAllBytes(
        "NotoSans-Subset-Regular.ttf"));
var hebrew = FontFace.Load(
    File.ReadAllBytes(
        "NotoSansHebrew-Subset-Regular.ttf"));
var chain = new FontFallbackChain(
    [latin, hebrew]);
var clusters = chain.ShapeRun("Aא🦄");
foreach (var cluster in clusters)
    Console.WriteLine(cluster.FaceIndex);

Unzip the example, then dotnet run.

Prints:

Text
0
1
0

The full program

The input is Aא🦄: Latin A, Hebrew alef and a unicorn emoji. Faces 0 and 1 are the Latin and Hebrew subsets. Neither contains the unicorn; it stays on face 0 as a missing glyph. The full program also prints each cluster’s text and missing-glyph status.

C#
using OneFont;
 
var latin = FontFace.Load(File.ReadAllBytes("NotoSans-Subset-Regular.ttf"));
var hebrew = FontFace.Load(File.ReadAllBytes("NotoSansHebrew-Subset-Regular.ttf"));
var chain = new FontFallbackChain([latin, hebrew]);
string text = "Aא🦄";
foreach (var cluster in chain.ShapeRun(text))
    Console.WriteLine($"{text.Substring(cluster.Start, cluster.Length)}: face {cluster.FaceIndex}, missing {cluster.HasMissingGlyph}");

dotnet run prints:

Text
A: face 0, missing False
א: face 1, missing False
🦄: face 0, missing True

Malformed font data throws FontFormatException; unsupported characters instead remain in the output as missing glyphs.

Variations

Reverse the preference order and inspect character selection without shaping:

C#
using OneFont;
 
var latin = FontFace.Load(File.ReadAllBytes(
    "NotoSans-Subset-Regular.ttf"));
var hebrew = FontFace.Load(File.ReadAllBytes(
    "NotoSansHebrew-Subset-Regular.ttf"));
var chain = new FontFallbackChain([hebrew, latin]);
Console.WriteLine(chain.SelectFace('א'));
Console.WriteLine(chain.SelectFace('A'));
Console.WriteLine(chain.SelectFace(0x1F984));
Text
0
1
0

Check font character coverage


The short answer

Load your font faces, put them in preference order in a FontFallbackChain, and call ShapeRun. Each result cluster has a FaceIndex into the chain and a HasMissingGlyph flag. Retain that association: a glyph ID is meaningful within the face that produced it, not across every font in your application.

The example needs no installed fonts. It ships two small Noto subsets and their license, loads them as bytes, and shapes a literal string. The last character deliberately has no matching face, so the output shows both successful fallback and the failure behavior a multilingual application must handle.

What is a fallback font?

A fallback font supplies characters that your preferred font does not cover. In onefont the chain is explicit: it is not a search through the operating system’s installed fonts. Your application chooses and loads the available faces, orders them, and decides what to do with remaining missing glyphs.

The pinned documentation defines a specific selection rule: for each grapheme cluster, select the first face with a glyph for the cluster’s first character. That is not a guarantee that the face covers every combining mark or other character in the cluster. A base letter can select a face whose coverage is incomplete for the rest of that cluster. Inspect the shaped result rather than assuming that choosing a face proves complete coverage.

If no face covers the first character, the cluster stays on the first face and uses its missing-glyph box. Reversing the chain therefore changes both preference and the destination for uncovered characters. SelectFace returns zero in that case too: zero alone cannot distinguish successful selection of the first face from no coverage anywhere. HasMissingGlyph on the shaped clusters gives the useful result-level check.

How do I use font fallback for text shaping?

The full program above demonstrates face selection and prints missing status. Each stretch assigned to one face is shaped separately using that font’s OpenType tables. A shaped cluster never spans two faces. Invisible characters, including controls, joiners, soft hyphens and bidi controls, stay with the face of the preceding cluster.

ShapeRun shapes a run in one direction and returns clusters in logical order. The mixed-script sample inspects font assignment; it does not draw a paragraph or resolve its visual ordering. Set the direction for a directional run, and handle paragraph-level bidirectional ordering as a separate concern when your layout needs it.

Advances are in each cluster’s own font design units. To turn an advance into a display distance, scale it by the requested size divided by chain.Faces[cluster.FaceIndex].UnitsPerEm. Do not use the primary font’s units-per-em value for every fallback face: fonts need not use the same design grid.

Shaping also does not draw the text. Keep text layout and rendering separate from this selection step. The library supplies glyph outlines, but does not draw color glyphs; the unicorn here is an intentional missing-character example, not an emoji renderer. Choose redistributable fonts with the scripts you need, preserve their licenses, and test clusters containing marks as well as standalone letters.

Source: onefont fallback documentation.

All onefont recipes