# Fonts (/xml/assets/fonts)



<br />

<hr />

Overview [#overview]

In XML, fonts are considered external resources. A target font engine needs to be selected
and named in order to be referenced in XML files later.

Registering Fonts [#registering-fonts]

From File [#from-file]

Fonts used directly from a TTF file can be listed in the `<fonts>` section
of `globals.xml`.

Each child of `<fonts>` starts with the desired font engine's name, a
`name` property, and other properties depending on the selected engine.

`as_file` must be set to `true` to indicate that the font is treated as a file.

For example:

```xml title="xml" lineNumbers=1
<globals>
    <fonts>
        <bin as_file="false" name="medium" src="path/to/file.ttf" range="0x20-0x7f" symbols="°" size="24"/>
        <tiny_ttf as_file="true" name="big" src_path="path/to/file.ttf" range="0x20-0x7f" size="48"/>
    </fonts>
</globals>
```

When registering `globals.xml` with
<ApiLink name="lv_xml_register_component_from_file" display="lv_xml_register_component_from_file(&#x22;A:path/to/globals.xml&#x22;)" />,
fonts are automatically created with the selected font engine and mapped to the given names.

The fonts can have relative paths in `globals.xml`. Before registering `globals.xml`,
<ApiLink name="lv_xml_set_default_asset_path" display="lv_xml_set_default_asset_path(&#x22;path/prefix/&#x22;)" /> can be called to set the parent folder.
The font paths will then be appended to this base path.

From Data [#from-data]

If a font is used from C data (arrays) compiled into the firmware, the font's pointer can be registered
to XML like this:

```c title=" " lineNumbers=1
lv_xml_register_font(scope, "font_name", &my_font);
```

Fonts must be registered before any XML files referencing them are registered, so that the font data
is already known.

In LVGL's UI Editor, when using fonts as data, it's also necessary to add the fonts to
`globals.xml` with `as_file=false`, so the Editor can generate the required
C files and also perform validation when referencing data fonts.

Usage in XML [#usage-in-xml]

Once a font is registered, it can be referenced by its name in styles or even `<api>` properties:

```xml title="xml" lineNumbers=1
<component>
    <api>
        <prop name="title_font" type="font" default="my_font_32"/>
    </api>

    <styles>
        <style name="subtitle" text_font="my_font_24"/>
    </styles>

    <view flex_flow="column">
        <lv_label style_text_font="$title_font" text="Title"/>
        <lv_label text="I'm the subtitle">
            <style name="subtitle"/>
        </lv_label>
    </view>
```

Font Engines [#font-engines]

`<bin>` [#bin]

Binary fonts can either reference:

1. A ".bin" font file created by LVGL's Font converter from a TTF file (when `as_file="true"`).
   The font will be loaded by <ApiLink name="lv_binfont_create" />.
2. An <ApiLink name="lv_font_t" /> pointer compiled into the firmware (`as_file="false"`).
   No loading is needed as <ApiLink name="lv_font_t" /> can be used directly.

`<bin>` fonts require these properties:

| Field      | Description                                                                                |
| ---------- | ------------------------------------------------------------------------------------------ |
| `name`     | The name to reference the font later                                                       |
| `src_path` | Path to the font file                                                                      |
| `size`     | Font size in px (e.g., "12")                                                               |
| `bpp`      | Bits-per-pixel: 1, 2, 4, or 8                                                              |
| `as_file`  | `true` if the font is a ".bin" file, `false` if it is an <ApiLink name="lv_font_t" /> in C |

LVGL's UI Editor always generates a call to <ApiLink name="lv_xml_register_font" /> using the set `name`.
If `as_file` is:

* `false`: It generates a C file with the <ApiLink name="lv_font_t" /> structs.
* `true`: It generates a ".bin" file.

Binary fonts also support selecting a subset of characters:

| Field     | Description                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `range`   | For example, `"0x30-0x39 0x100-0x200"` to specify Unicode ranges to include. The default is `"0x20-0x7F"` to cover the ASCII range. |
| `symbols` | List of extra characters to add, e.g., `"°ÁŐÚ"`. Can be used together with `range`. Default is empty (no extras).                   |

`<tiny_ttf>` [#tiny_ttf]

TinyTTF fonts use the [Tiny TTF Font Engine](/libs/font_support/tiny_ttf) engine to load TTF files directly or from data.

Required properties:

| Field      | Description                          |
| ---------- | ------------------------------------ |
| `name`     | The name to reference the font later |
| `src_path` | Path to the font file                |
| `size`     | Font size in px (e.g., "12")         |
| `as_file`  | `true` or `false`                    |

LVGL's UI Editor generates a call to <ApiLink name="lv_xml_register_font" /> using the set `name`.
If `as_file` is:

* `false`: A C file with raw file data is also generated.
* `true`: Nothing else is generated, as the TTF file will be used directly.

`<freetype>` [#freetype]

FreeType fonts use the [FreeType Font Engine](/libs/font_support/freetype) engine to load TTF files directly. Loading from data is not supported,
so `as_file` is always considered `true`.

Required properties:

| Field      | Description                          |
| ---------- | ------------------------------------ |
| `name`     | The name to reference the font later |
| `src_path` | Path to the font file                |
| `size`     | Font size in px (e.g., "12")         |

LVGL's UI Editor generates a call to <ApiLink name="lv_xml_register_font" /> using the set `name`.