wezterm.font_with_fallback(families [, attributes])¶
This function constructs a lua table that configures a font with fallback processing. Glyphs are looked up in the first font in the list but if missing the next font is checked and so on.
The first parameter is a table listing the fonts in their preferred order:
WezTerm implicitly adds its default fallback to the list that you specify.
The attributes parameter behaves the same as that of wezterm.font in that it allows you to specify font weight and style attributes that you want to match.
Since: Version 20210502-130208-bff6815d
The functionality described in this section requires version 20210502-130208-bff6815d of wezterm, or a more recent version.
The attributes can now be specified per fallback font using this alternative form where the family and attributes are specified as part of the same lua table:
Since: Version 20220101-133340-7edc5b5a
The functionality described in this section requires version 20220101-133340-7edc5b5a of wezterm, or a more recent version.
You can use the expanded form mentioned above to override freetype and harfbuzz settings just for the specified font; this examples shows how to disable the default ligature feature just for JetBrains Mono, but leave it on for the other fonts in the fallback:
The following options can be specified in the same way:
assume_emoji_presentation = trueor
assume_emoji_presentation = falseto control whether a font is considered to have emoji (rather than text) presentation glyphs for emoji. (Since: Version 20220807-113146-c2fee766)
Dealing with different fallback font heights¶
When mixing different font families there is a chance that glyphs from one font don't appear to be the same height as the glyphs from your primary font.
For "Roman" fonts there exists a font metric known as cap-height which indicates the nominal size of a capital (uppercase) letter that can be used to compute a scaling factor that can be used to make the fallback font appear to have the same size.
true will cause wezterm to try to automatically scale using the
cap-height metric (or to compute its own idea of the cap-height based on the size of
Manual fallback scaling¶
Since: Version 20220408-101518-b908e2dd
The functionality described in this section requires version 20220408-101518-b908e2dd of wezterm, or a more recent version.
CJK fonts typically won't have a useful cap-height metric so it may be desirable to manually configure the fallback scaling factor to boost the size of the CJK font so that the glyphs are more readable.
The example below shows how to boost the effective size of the
YaHei" fallback font to
1.5 times the normal size. The boost cannot
influence font metrics so it may be desirable to also specify
line_height to produce a more pleasing display.