> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# wezterm.font() and font_with_fallback()

> Configure fonts with attributes and fallback support for WezTerm

## wezterm.font()

Constructs a font configuration for a single named font with optional style attributes.

### Signature

```lua theme={null}
function wezterm.font(
  family: string,
  attributes?: FontAttributes
) -> TextStyle

function wezterm.font(
  font_spec: FontSpec
) -> TextStyle
```

### Parameters

<ParamField path="family" type="string" required>
  The font family name. Can be one of:

  * **Family name** (recommended): `"JetBrains Mono"` - doesn't include style info
  * **Full name**: `"JetBrains Mono Regular"` - includes sub-family
  * **PostScript name**: Unique identifier encoded by font designer
</ParamField>

<ParamField path="attributes" type="FontAttributes">
  Optional table specifying font style attributes:

  <ParamField path="weight" type="string" default="Regular">
    Font weight. Options:

    * `"Thin"`
    * `"ExtraLight"`
    * `"Light"`
    * `"DemiLight"`
    * `"Book"`
    * `"Regular"` (default)
    * `"Medium"`
    * `"DemiBold"`
    * `"Bold"`
    * `"ExtraBold"`
    * `"Black"`
    * `"ExtraBlack"`
  </ParamField>

  <ParamField path="stretch" type="string" default="Normal">
    Font stretch. Options:

    * `"UltraCondensed"`
    * `"ExtraCondensed"`
    * `"Condensed"`
    * `"SemiCondensed"`
    * `"Normal"` (default)
    * `"SemiExpanded"`
    * `"Expanded"`
    * `"ExtraExpanded"`
    * `"UltraExpanded"`
  </ParamField>

  <ParamField path="style" type="string" default="Normal">
    Font style. Options:

    * `"Normal"` (default)
    * `"Italic"` - distinctive design at an angle
    * `"Oblique"` - similar to Normal but skewed
  </ParamField>

  <ParamField path="harfbuzz_features" type="string[]">
    HarfBuzz font shaping features to enable/disable.
    Example: `{ 'calt=0', 'clig=0', 'liga=0' }` to disable ligatures
  </ParamField>

  <ParamField path="freetype_load_target" type="string">
    FreeType load target hint setting
  </ParamField>

  <ParamField path="freetype_render_target" type="string">
    FreeType render target setting
  </ParamField>

  <ParamField path="freetype_load_flags" type="string">
    FreeType load flags
  </ParamField>

  <ParamField path="assume_emoji_presentation" type="boolean">
    Control whether font is considered to have emoji presentation glyphs
  </ParamField>
</ParamField>

### Return Value

<ResponseField name="TextStyle" type="object">
  A text style object containing font configuration that can be assigned to config.font
</ResponseField>

### Basic Examples

<CodeGroup>
  ```lua Simple Usage theme={null}
  local wezterm = require 'wezterm'

  return {
    font = wezterm.font('JetBrains Mono'),
  }
  ```

  ```lua With Attributes theme={null}
  local wezterm = require 'wezterm'

  return {
    font = wezterm.font('JetBrains Mono', { weight = 'Bold' }),
  }
  ```

  ```lua Extended Attributes theme={null}
  local wezterm = require 'wezterm'

  return {
    font = wezterm.font(
      'Iosevka Term',
      { stretch = 'Expanded', weight = 'Regular' }
    ),
  }
  ```

  ```lua Table Syntax theme={null}
  local wezterm = require 'wezterm'

  return {
    font = wezterm.font {
      family = 'Iosevka Term',
      stretch = 'Expanded',
      weight = 'Regular',
    },
  }
  ```
</CodeGroup>

### Advanced Features

#### Disable Ligatures

You can disable ligatures for specific fonts:

```lua theme={null}
local wezterm = require 'wezterm'

return {
  font = wezterm.font {
    family = 'JetBrains Mono',
    harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
  },
}
```

#### Emoji Presentation

Control whether a font is considered to have emoji glyphs:

```lua theme={null}
local wezterm = require 'wezterm'

return {
  font = wezterm.font {
    family = 'MyFont',
    assume_emoji_presentation = true,
  },
}
```

## wezterm.font\_with\_fallback()

Constructs a font configuration with fallback fonts. Glyphs are looked up in the first font, but if missing, the next font is checked, and so on.

### Signature

```lua theme={null}
function wezterm.font_with_fallback(
  families: (string | FontSpec)[],
  attributes?: FontAttributes
) -> TextStyle
```

### Parameters

<ParamField path="families" type="array" required>
  Array of font families in preferred order. Each element can be:

  * A string font family name
  * A table with family and per-font attributes
</ParamField>

<ParamField path="attributes" type="FontAttributes">
  Optional attributes applied to all fonts (unless overridden per-font)
</ParamField>

### Return Value

<ResponseField name="TextStyle" type="object">
  A text style object with multiple fonts configured in fallback order
</ResponseField>

### Examples

<CodeGroup>
  ```lua Basic Fallback theme={null}
  local wezterm = require 'wezterm'

  return {
    font = wezterm.font_with_fallback {
      'JetBrains Mono',
      'Noto Color Emoji',
    },
  }
  ```

  ```lua Per-Font Attributes theme={null}
  local wezterm = require 'wezterm'

  return {
    font = wezterm.font_with_fallback {
      { family = 'JetBrains Mono', weight = 'Medium' },
      { family = 'Terminus', weight = 'Bold' },
      'Noto Color Emoji',
    },
  }
  ```

  ```lua Disable Ligatures for Primary theme={null}
  local wezterm = require 'wezterm'

  return {
    font = wezterm.font_with_fallback {
      {
        family = 'JetBrains Mono',
        harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
      },
      { family = 'Terminus', weight = 'Bold' },
      'Noto Color Emoji',
    },
  }
  ```

  ```lua CJK with Scaling theme={null}
  local wezterm = require 'wezterm'

  return {
    line_height = 1.2,
    font = wezterm.font_with_fallback {
      'JetBrains Mono',
      { family = 'Microsoft YaHei', scale = 1.5 },
    },
  }
  ```
</CodeGroup>

### Fallback Font Scaling

When mixing different font families, glyphs may appear to have different heights. WezTerm provides two ways to handle this:

#### Automatic Scaling

Use the `use_cap_height_to_scale_fallback_fonts` config option:

```lua theme={null}
local wezterm = require 'wezterm'

return {
  use_cap_height_to_scale_fallback_fonts = true,
  font = wezterm.font_with_fallback {
    'JetBrains Mono',
    'Noto Sans CJK',
  },
}
```

This uses the font's cap-height metric (or computes it) to automatically scale fallback fonts.

#### Manual Scaling

For CJK fonts or when automatic scaling doesn't work well, manually specify the scale factor:

```lua theme={null}
local wezterm = require 'wezterm'

return {
  line_height = 1.2,
  font = wezterm.font_with_fallback {
    'JetBrains Mono',
    { family = 'Microsoft YaHei', scale = 1.5 },
  },
}
```

<Note>
  Manual scaling cannot influence font metrics, so you may also need to adjust `line_height` for better appearance.
</Note>

## Font Resolution

WezTerm follows **CSS Fonts Level 3** compatible font matching when resolving fonts:

1. **Exact match**: Tries to find a font that exactly matches the specified attributes
2. **Close match**: If no exact match, finds a close match within the font family
3. **Fallback**: If a glyph is missing, tries the next font in the fallback list

<Warning>
  WezTerm can only use fonts installed on your system. If you request a condensed variant, you must have the condensed font file installed. WezTerm can synthesize basic bold and oblique for non-bitmap fonts, but this is not recommended.
</Warning>

## Important Notes

* **Use family names**: The family name (without style info) is the most compatible
* **Install all variants**: If you want condensed, bold, or italic fonts, install those font files
* **Implicit fallbacks**: WezTerm adds its own default fallback fonts to your list
* **Font files required**: All fonts must be installed on your system

## Related Configuration

* `font_size` - Set the font point size
* `font_dirs` - Additional directories to search for fonts
* `line_height` - Adjust line height multiplier
* `use_cap_height_to_scale_fallback_fonts` - Automatic fallback scaling

## Source Reference

Implementation: `config/src/lua.rs:552-641`