How to Fix LVGL Font Errors in ESP32-S3 Projects SquareLine Studio Export Guide with ESP-IDF (LVGL v8.3.11)

Introduction: The “Undeclared Font” Nightmare

In embedded GUI development, the combination of ESP32-S3, LVGL, and SquareLine Studio has become a practical industry standard. This toolchain enables developers to build smartphone-like user interfaces for industrial controllers, IoT dashboards, and smart appliances such as a Smart Laundry Controller.

However, many developers encounter a critical roadblock during compilation.

You design a clean screen, select a large bold font—such as Montserrat 46 for displaying prices—export the UI from SquareLine Studio, press Build, and suddenly face this fatal error:

error: 'lv_font_montserrat_46' undeclared (first use in this function)

The font clearly exists in SquareLine Studio, so why does the compiler fail?

The answer lies in the interaction between LVGL’s modular design, ESP-IDF’s component-based build system, and how LVGL configuration headers are resolved at compile time.
This article explains the root cause and provides a reliable, production-ready solution.

1. Core Concepts: Why This Error Occurs

The Modular Nature of LVGL

LVGL is designed to be lightweight and memory-efficient. To minimize Flash and RAM usage, every font size is conditionally compiled using C preprocessor macros.

By default, LVGL enables only a small set of fonts (typically Montserrat 14).

When SquareLine Studio generates code such as:

lv_obj_set_style_text_font(ui_Label, &lv_font_montserrat_46, 0);

it assumes that the corresponding font has already been enabled inside lv_conf.h.

If the font macro is disabled, the symbol lv_font_montserrat_46 is never compiled, resulting in an “undeclared” error.

The ESP-IDF Component System

ESP-IDF treats every directory inside components/ as an independent module.
Each component must explicitly declare:

• Source files

• Include paths

• Dependencies

If LVGL, the UI component, or lv_conf.h are placed incorrectly, ESP-IDF may compile LVGL without your configuration, even if you edited the correct file.

2. The Perfect Folder Structure (ESP-IDF v5.x Standard)

smart_project/
├── CMakeLists.txt
├── main/
│   ├── CMakeLists.txt
│   └── main.c
├── components/
│   ├── lvgl/
│   │   ├── src/
│   │   ├── env_support/
│   │   └── CMakeLists.txt
│   ├── ui/
│   │   ├── components/
│   │   ├── fonts/
│   │   ├── images/
│   │   ├── screens/
│   │   ├── ui.c
│   │   ├── ui.h
│   │   └── CMakeLists.txt
│   └── lv_conf.h
└── build/

Why This Structure Matters

• Single global lv_conf.h
  Placing it under components/ ensures it is visible to both LVGL and SquareLine-generated UI code.

• Separated UI component
  Makes LVGL upgrades safe and avoids mixing library code with generated UI logic.

3. CMakeLists.txt Configuration (Mandatory)

A. Root CMakeLists.txt

cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(smart_laundry)

B. LVGL Component CMakeLists.txt

set(LVGL_ROOT_DIR ${CMAKE_CURRENT_LIST_DIR})

if(ESP_PLATFORM)
    include(${CMAKE_CURRENT_LIST_DIR}/env_support/cmake/esp.cmake)
endif()

C. UI Component CMakeLists.txt

file(GLOB_RECURSE SOURCES *.c)

idf_component_register(
    SRCS ${SOURCES}
    INCLUDE_DIRS .
    PRIV_REQUIRES lvgl
)

4. Choosing the Correct LVGL Version (Critical for SquareLine)

Why LVGL v8.3.11 Is Recommended

SquareLine Studio (current stable releases) is designed around LVGL 8.x, and v8.3.11 is the most stable and widely tested version for ESP32-S3.

Benefits:

• Fully compatible with SquareLine exports

• Stable font subsystem

• Mature ESP-IDF integration

• No breaking API changes

⚠ Using LVGL 9.x will cause font symbols, styles, and APIs to break unless SquareLine explicitly supports it.

Recommendation:
✔ Lock LVGL to v8.3.11
✔ Match SquareLine project LVGL version exactly

5. Mastering lv_conf.h: Enabling Fonts Correctly

Step 1: Enable the Configuration File

#if 1 /* Set this to "1" to enable content */

If this is set to 0, LVGL ignores everything below it.

Step 2: Enable Required Built-In Fonts

#define LV_FONT_MONTSERRAT_12 1
#define LV_FONT_MONTSERRAT_14 1
#define LV_FONT_MONTSERRAT_24 1
#define LV_FONT_MONTSERRAT_44 1
#define LV_FONT_MONTSERRAT_46 1
#define LV_FONT_MONTSERRAT_48 1

LVGL will now compile the corresponding font data and expose the symbols.

Step 3: Custom Fonts Exported by SquareLine

If SquareLine exports fonts into components/ui/fonts/:

• Ensure .c files exist

• Ensure they are included by file(GLOB_RECURSE *.c)

• No additional #define is required

6. Ensuring UI Sees the Correct Configuration

Force the configuration include in ui.h:

#define LV_CONF_INCLUDE_SIMPLE 1
#include "lv_conf.h"
#include "lvgl.h"

This guarantees consistent font availability across all UI files.

7. The Build Cache Trap (Why Errors Persist)

ESP-IDF uses Ninja, which aggressively caches results.

Font macro changes often do not trigger recompilation automatically.

Always Run:

idf.py fullclean
idf.py build

Or delete the build/ directory manually.

8. Conclusion: From Font Errors to a Working UI

To successfully use large fonts in SquareLine-generated LVGL projects:

1. Use LVGL v8.3.11

2. Place lv_conf.h correctly

3. Enable fonts explicitly

4. Configure CMake properly

5. Always fullclean after font changes

Once these steps are followed, SquareLine Studio exports compile cleanly and run reliably on ESP32-S3.

Next Steps

• Verify your display driver (RGB LCD, ST7789, ILI9341)

• Match SquareLine resolution with hardware

• Implement ui_event callbacks to control real laundry hardware