---
title: "Shape text with font fallback in C#"
url: https://recursiveai.org/onefont/cookbook/shape-text-with-font-fallback/
description: "Build an ordered font fallback chain, shape mixed Latin and Hebrew text, inspect the selected face per cluster, and detect missing glyphs in C#."
version: "1.4.0"
---

# 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.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneFont) · [GitHub](https://github.com/recursive-ai-oss/onefont-csharp) · [Docs](https://recursiveai.org/onefont/docs/) · [Download example (.zip)](https://recursiveai.org/onefont/cookbook/shape-text-with-font-fallback/shape-text-with-font-fallback.zip)

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

```shell
dotnet add package RecursiveAI.OneFont
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

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

```csharp
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](https://recursiveai.org/onefont/cookbook/shape-text-with-font-fallback/shape-text-with-font-fallback.zip), 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.

```csharp
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:

```csharp
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
```

## Related recipes

[Check font character coverage](https://recursiveai.org/onefont/cookbook/font-supports-character/)

---

## 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](https://recursiveai.org/onefont/docs/shaping/#fallback).
