LVGL turns a plain TFT display into a real interface. With TFT_eSPI alone, your code draws pixels, lines, and text by hand. With LVGL on top, you get buttons, sliders, gauges, menus, and touch input.
Short answer: install the LVGL 9 library in the Arduino IDE, set up TFT_eSPI for your display driver, connect the two with a flush callback or the LVGL TFT_eSPI helper, then build your screen from widgets. The worked example uses the 2.4 inch touch ILI9341 module from the store. This draft is written against LVGL 9.x, verified against the LVGL docs and the Random Nerd Tutorials LVGL 9.2 example.
What is LVGL, and when should you use it instead of TFT_eSPI alone?
LVGL stands for Light and Versatile Graphics Library. It is a free and open-source graphics library for microcontrollers, released under the MIT license. It gives you widgets (buttons, labels, sliders, charts, lists, images), layout management, event handling, animations, CSS-like styling, multi-language support with UTF-8, and support for touchpads, mice, keyboards, and encoders. It is written in C. Source: LVGL docs and Random Nerd Tutorials.
LVGL does not drive your display. LVGL renders your interface into a memory buffer, then calls a function you provide, the flush callback, to move those pixels to the screen. The display driver, usually TFT_eSPI on an ESP32 SPI display, does the actual SPI transfer.
Use TFT_eSPI alone when the screen shows fixed text, a simple readout, or a static gauge. Use LVGL when the screen needs buttons, menus, sliders, or screens the user navigates. If you have not installed TFT_eSPI yet, follow our TFT_eSPI setup guide first.
Which LVGL version is this guide written against?
This guide is written against LVGL 9.x. The worked Arduino example follows the Random Nerd Tutorials guide, which installs LVGL version 9.2 from the Arduino Library Manager. The LVGL documentation site currently serves the 9.4 docs.
| Item | LVGL 8.x | LVGL 9.x (this guide) |
|---|---|---|
| Display driver | lv_disp_drv_t, lv_disp_drv_register | lv_display_t, lv_display_create |
| Draw buffer | lv_disp_draw_buf_t | Buffers passed to lv_display_create |
| Flush ready call | lv_disp_flush_ready | lv_display_flush_ready |
| Input device | lv_indev_drv_t, lv_indev_drv_register | lv_indev_t, lv_indev_create |
| Active screen | lv_scr_act() | lv_screen_active() |
| Button create | lv_btn_create | lv_button_create |
| Main loop call | lv_task_handler | lv_timer_handler |
Source: LVGL 9 docs and the ElectricalFlux LVGL ESP32-S3 guide.
What do you need before you start?
- An ESP32 board. This guide uses the ESP32 DevKit V1, the same board as the TFT_eSPI setup guide, because its hardware SPI pins match the library examples.
- A separate SPI TFT module. The worked examples use the 2.4 inch touch ILI9341 module and the 0.96 inch ST7735 module from the store.
- The Arduino IDE with the ESP32 board package installed, version 2.x or later.
- TFT_eSPI installed and configured for your display, per our TFT_eSPI setup guide. A setup that already passes its Colour_Test sketch is the starting point.
- Jumper wires and a breadboard. Keep the SPI wires short: long wires cause signal problems at full SPI speed.
How do you install LVGL in the Arduino IDE?
Open the Library Manager: Sketch, Include Library, Manage Libraries. Search for “lvgl”, find the entry by kisvegabor, and install version 9.2 or later in the 9.x line. Do not install a version 8 release alongside it: one LVGL version per project, and the code in this guide is written for 9.x.
Then prepare the LVGL config file, lv_conf.h. LVGL ships with a template file, lv_conf_template.h, inside the library folder. Copy it, rename the copy to lv_conf.h, and place it in your Arduino libraries folder, not inside the lvgl folder.
Open lv_conf.h and check two settings: the guard near the top that disables the whole file when it is set to 0 must be set to 1, and color depth LV_COLOR_DEPTH must be 16 (RGB565, the 16-bit color TFT_eSPI sends to the display). Your sketch starts with two lines that tell LVGL to use this config file:
#define LV_CONF_INCLUDE_SIMPLE
#include <lvgl.h>
Source: Random Nerd Tutorials LVGL 9.2 guide and the CircuitDigest LVGL Arduino tutorial. If the sketch fails to compile with errors about lv_conf.h not found, the file is in the wrong folder.
How do you wire the display?
Use the same wiring as the TFT_eSPI setup guide. LVGL does not change the wiring: TFT_eSPI still owns the SPI bus, and LVGL only hands it pixels. For an ESP32 DevKit V1 the display wires to the hardware SPI pins: MOSI 23, MISO 19, SCLK 18, CS 15, DC 2, RST 4, with VCC at 3.3V and BLK at 3V3 or a free GPIO for dimming. Connect MISO even if you think you do not need it: the display ID read and the touch controller need it. The full wiring table and the User_Setup.h edit for each driver are in our TFT_eSPI setup guide.
Which display drivers does LVGL work with?
LVGL works with any display driver that can move a rectangle of pixels to the screen. For the store TFT modules, the driver is TFT_eSPI: it supports the ST7735, ST7789, ILI9341, ILI9488, and ST7796 chips, per the TFT_eSPI README. The GC9A01 round display needs its own low-level driver code, as in the CircuitDigest LVGL tutorial. The built-in 1.9 inch ST7789 board (ID 17819) works the same way: TFT_eSPI with the ST7789 driver at 170 by 320, CS 5, RST 4, BL 32, and MOSI 23.
How do you bind LVGL to your display driver?
Binding means telling LVGL three things: how big the screen is, where to put rendered pixels while they wait, and which function moves them to the display. Route A is the one to use with TFT_eSPI. Route B is the manual route, for other display drivers.
Route A: the TFT_eSPI helper (use this first)
LVGL 9 ships a helper that binds TFT_eSPI in one call. The Random Nerd Tutorials LVGL 9.2 example uses it, and it needs no flush callback of your own:
#define SCREEN_WIDTH 240
#define SCREEN_HEIGHT 320
#define DRAW_BUF_SIZE (SCREEN_WIDTH * SCREEN_HEIGHT / 10 * (LV_COLOR_DEPTH / 8))
uint32_t draw_buf[DRAW_BUF_SIZE / 4];
void setup() {
Serial.begin(115200);
lv_init();
lv_display_t * disp;
disp = lv_tft_espi_create(SCREEN_WIDTH, SCREEN_HEIGHT, draw_buf, sizeof(draw_buf));
lv_display_set_rotation(disp, LV_DISPLAY_ROTATION_270);
}
lv_tft_espi_create creates the LVGL display, registers the TFT_eSPI flush function behind the scenes, and attaches your draw buffer. The rotation call turns the portrait 240 by 320 panel into landscape. Source: Random Nerd Tutorials.
DRAW_BUF_SIZE is one tenth of the screen, in 16-bit pixels: 7,680 pixels, or 15,360 bytes, for a 240 by 320 screen. A bigger buffer means smoother animation but costs RAM. If animations stutter, raise it to one quarter. If the sketch crashes on boot, shrink it.
Route B: the manual flush callback
If your display driver is not TFT_eSPI, write the flush callback yourself. LVGL calls it whenever a rectangle of the screen needs updating. The callback receives the display, the rectangle (area), and the pixel data (px_map), sends that rectangle to the screen, then tells LVGL the buffer is free:
void my_disp_flush(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map)
{
uint32_t w = (area->x2 - area->x1 + 1);
uint32_t h = (area->y2 - area->y1 + 1);
lcd.startWrite();
lcd.setAddrWindow(area->x1, area->y1, w, h);
lcd.pushColors((uint16_t *)px_map, w * h, true);
lcd.endWrite();
lv_display_flush_ready(disp);
}
The area coordinates are inclusive, so both dimensions need plus 1. lv_display_flush_ready(disp) is not optional: without it, LVGL waits forever for a buffer that never comes back, and the screen freezes after the first frame. Register the callback with lv_display_create, lv_display_set_buffers, and lv_display_set_flush_cb. Source: SmartDocs. Two buffers give double buffering; one buffer works too and uses half the RAM.
How do you build the first screen?
Once the display is bound, the rest is widgets. This example is adapted from the Random Nerd Tutorials LVGL 9.2 sketch: a label, a button that counts clicks, and a slider that prints its value.
void lv_create_main_gui(void) {
lv_obj_t * text_label = lv_label_create(lv_screen_active());
lv_label_set_text(text_label, "Hello, world!");
lv_obj_align(text_label, LV_ALIGN_CENTER, 0, -90);
lv_obj_t * btn1 = lv_button_create(lv_screen_active());
lv_obj_add_event_cb(btn1, event_handler_btn1, LV_EVENT_ALL, NULL);
lv_obj_align(btn1, LV_ALIGN_CENTER, 0, -50);
lv_obj_t * btn_label = lv_label_create(btn1);
lv_label_set_text(btn_label, "Button");
lv_obj_center(btn_label);
lv_obj_t * slider = lv_slider_create(lv_screen_active());
lv_obj_align(slider, LV_ALIGN_CENTER, 0, 60);
lv_obj_add_event_cb(slider, slider_event_callback, LV_EVENT_VALUE_CHANGED, NULL);
lv_slider_set_range(slider, 0, 100);
}
The event callback reads the event code and acts on it:
static void event_handler_btn1(lv_event_t * e) {
lv_event_code_t code = lv_event_get_code(e);
if(code == LV_EVENT_CLICKED) {
btn1_count++;
}
}
And the main loop hands time to LVGL. LVGL needs a millisecond tick and regular calls to its handler, or nothing moves: no animations, no touch, no screen updates.
void loop() {
lv_timer_handler();
lv_tick_inc(5);
delay(5);
}
Source: Random Nerd Tutorials. Note that their code calls the handler lv_task_handler, the LVGL 8 name. In LVGL 9 the function is lv_timer_handler. If your loop blocks for more than a few milliseconds, the interface freezes for the same time.
Which widgets should you use?
Every widget follows the same pattern: create it on a parent, set its size and position, style it, and add an event callback if it takes input.
| Widget | Create call (LVGL 9) | Use it for |
|---|---|---|
| Label | lv_label_create | Text, readouts, titles |
| Button | lv_button_create | Actions, toggles, navigation |
| Slider | lv_slider_create | Brightness, volume, setpoints from 0 to 100 |
| Bar | lv_bar_create | Progress, battery level, signal strength |
LVGL also has arcs, charts, images, dropdowns, switches, keyboards, text areas, menus, tabs, tables, and animations; the full list is in the LVGL docs widget section. Two rules apply to all of them. First, every object has a parent: a widget created with no parent goes on the active screen, and a widget created on a button becomes part of that button, like the label inside btn1 above. Second, styles are CSS-like: set colors, fonts, padding, and radius per widget, or per state, such as pressed or checked. Source: Random Nerd Tutorials and the LVGL docs widget examples.
How do you add touch input?
A touch display needs a second driver: one for the screen, one for the touch controller. The touch modules in the store use the XPT2046 resistive touch controller. The steps below follow the Random Nerd Tutorials LVGL 9.2 example.
Install the XPT2046_Touchscreen library from the Library Manager, then define the touch pins and start a second SPI bus for the touch chip. The touch chip has its own chip select, so it shares MOSI, MISO, and SCK with the display:
#define XPT2046_IRQ 36
#define XPT2046_MOSI 32
#define XPT2046_MISO 39
#define XPT2046_CLK 25
#define XPT2046_CS 33
SPIClass touchscreenSPI = SPIClass(VSPI);
XPT2046_Touchscreen touchscreen(XPT2046_CS, XPT2046_IRQ);
In setup, start the touch SPI, begin the touchscreen, and set its rotation to match the display rotation. Then register the touch input device with LVGL and give it a read callback:
touchscreenSPI.begin(XPT2046_CLK, XPT2046_MISO, XPT2046_MOSI, XPT2046_CS);
touchscreen.begin(touchscreenSPI);
touchscreen.setRotation(2);
lv_indev_t * indev = lv_indev_create();
lv_indev_set_type(indev, LV_INDEV_TYPE_POINTER);
lv_indev_set_read_cb(indev, touchscreen_read);
The read callback checks the touch state, reads the point, and maps the raw touch values to screen pixels:
void touchscreen_read(lv_indev_t * indev, lv_indev_data_t * data) {
if(touchscreen.tirqTouched() && touchscreen.touched()) {
TS_Point p = touchscreen.getPoint();
x = map(p.x, 200, 3700, 1, SCREEN_WIDTH);
y = map(p.y, 240, 3800, 1, SCREEN_HEIGHT);
data->state = LV_INDEV_STATE_PRESSED;
data->point.x = x;
data->point.y = y;
}
else {
data->state = LV_INDEV_STATE_RELEASED;
}
}
Source: Random Nerd Tutorials. Two warnings. First, the calibration numbers in the map calls, 200 to 3700 on X and 240 to 3800 on Y, are the values for the 2.8 inch touch module in that tutorial, not the 2.4 inch touch module in the store. Read the raw touch values from your own module, then set the map limits to your module. A button that only responds on one side of the screen is almost always a calibration problem. Second, if the touch picture is upside down or mirrored, change the touchscreen rotation value, not the LVGL rotation.
How do you use fonts and images?
LVGL ships with built-in fonts, and it can load custom fonts and images.
Built-in fonts. LVGL includes the Montserrat font in several sizes, enabled in lv_conf.h. A label uses the default font unless you set another one with lv_obj_set_style_text_font. Keep the enabled set small: every font size adds flash use.
Custom fonts. For a font LVGL does not ship, use the LVGL font converter linked from the LVGL docs. It converts a font file into a C array you add to your sketch. Generate it for LVGL 9, not LVGL 8.
Images. LVGL shows images from C arrays compiled into the sketch, or from files on a filesystem such as an SD card. The LVGL image converter, also linked from the LVGL docs, turns a PNG or JPG into a C array. A full-screen photo at 240 by 320 in 16-bit color is about 150 kB, so keep images small or load them from a card.
What about the ESP-IDF path?
The Arduino path above is the fastest way to a working screen. The ESP-IDF path gives more control, and it is the path Espressif documents for production firmware. The LVGL docs page “Add LVGL to an ESP32 IDF project” covers it.
The simplest ESP-IDF route is the esp_lvgl_port component, which provides helper functions for installing LVGL and display drivers, plus touch, encoder, button, and USB HID input support:
idf.py create-project my_lvgl_app
cd my_lvgl_app
idf.py add-dependency "espressif/esp_lvgl_port^2.3.0"
The esp_lvgl_port component supports LVGL versions 8 and 9 and is compatible with ESP-IDF v5.2 and above. By default it pulls the latest stable LVGL, so pin a version if your project must stay on one. To add LVGL without the port component, use idf.py add-dependency “lvgl/lvgl^9.*”. Then configure LVGL with idf.py menuconfig and add a display driver and a touch driver from the ESP component registry. Source: LVGL docs, “Add LVGL to an ESP32 IDF project”.
What are the common mistakes?
- Mixing LVGL 8 code with LVGL 9. lv_disp_drv_t, lv_btn_create, lv_scr_act, and lv_task_handler are LVGL 8 names. LVGL 9 uses lv_display_t, lv_button_create, lv_screen_active, and lv_timer_handler. One version per project.
- A lv_conf.h from another tutorial. The config file must match your LVGL version and your display. Copy the template from your own installed library.
- Forgetting lv_display_flush_ready in a manual flush callback. The screen draws one frame, then freezes forever.
- No tick and no handler in loop. LVGL needs lv_tick_inc and lv_timer_handler called regularly. A blocking loop freezes the interface.
- A draw buffer that is too small or too big. Too small and animations stutter. Too big and the sketch crashes on boot. Start at one tenth of the screen, and set LV_COLOR_DEPTH to 16: the store TFT modules use 16-bit color.
How do you fix an LVGL display that does not work?
Work through the stack from the bottom up: wiring, TFT_eSPI, LVGL config, then your code.
The screen stays white or black after upload. Check the backlight first, then run Colour_Test without LVGL. If Colour_Test fails, the problem is wiring or User_Setup.h, not LVGL. Source: our TFT_eSPI setup guide.
The screen shows the first frame, then freezes. The flush callback never told LVGL the buffer was free. Check that lv_display_flush_ready(disp) runs at the end of your flush callback.
The picture is there but the colors are wrong. Check LV_COLOR_DEPTH is 16, and check the byte swap setting in TFT_eSPI. The SmartDocs guide lists enabling byte swapping with tft.setSwapBytes(true) as the fix for garbled colors. Source: SmartDocs.
Buttons do not respond to touch. Check lv_indev_create and lv_indev_set_read_cb ran in setup, check the touch CS pin, and check the calibration map limits. Source: SmartDocs and Random Nerd Tutorials.
Which route should you pick?
Match the tool to the job. For display selection, see our display buying guide.
| Project | Pick | Why |
|---|---|---|
| Temperature readout, clock, status text | TFT_eSPI alone | No buttons, no menus, less code |
| Thermostat with setpoint buttons | LVGL on TFT_eSPI, Route A | Buttons and a slider, one afternoon of work |
| Production firmware | LVGL on ESP-IDF with esp_lvgl_port | Version-pinned components and full control |
Parts used in this guide
Prices and stock were verified live on qualityrcparts.com on 2026-11-21 through the public Store API. All four items are in stock.
- 2.4 Inch SPI TFT LCD Touch Display Module, 240×320, ILI9341 driver (ID 17813) – $20.99. The touch module for the worked example: ILI9341 driver, touch panel and pen.
- 0.96 Inch TFT Display Module 2-Pack, Color IPS LCD 80×160, ST7735 SPI for Arduino ESP32 (ID 19625) – $13.99. Two ST7735 modules for a small LVGL status screen without touch.
- ESP32 Development Board with 1.9 Inch ST7789 TFT LCD Display, 16MB, WiFi + Bluetooth, USB-C (ID 17819) – $19.99. The built-in display board: no wiring, LVGL on TFT_eSPI with the ST7789 driver at 170 by 320.
- 2.4 Inch TFT LCD Display Module, 320×240 ST7789 SPI Color Screen, No Touch, for Arduino ESP32 ESP8266 (ID 19630) – $14.99. The no-touch 2.4 inch module for LVGL status screens and gauges.
Shipped fast and securely from our secure facility in Queensbury, NY. QRC ships within the USA only.
Related guides
- TFT_eSPI Setup Guide: Install, User_Setup.h, First Sketch
- ESP32 Boards with Built-In Displays: TFT vs OLED Compared
- OLED vs TFT Display: Which Is Best for ESP32 Projects?
- How to Choose the Right Display for Arduino or ESP32
- How to Choose ESP32 Boards for Your Robotics Projects
- XIAO ESP32 Pinout: C3, C6, S3, and C5 GPIO Tables
FAQ
What is LVGL? LVGL is the Light and Versatile Graphics Library, a free and open-source graphics library under the MIT license. It provides widgets such as buttons, labels, sliders, charts, and lists, plus layouts, styles, animations, and touch input. Source: LVGL docs and Random Nerd Tutorials.
Can I use LVGL with an ESP32 and a TFT display? Yes. Install LVGL 9 in the Arduino IDE, set up TFT_eSPI for your display driver, bind them with the TFT_eSPI helper or a flush callback, then build your screen from widgets. Source: Random Nerd Tutorials LVGL 9.2 guide.
Which LVGL version should I install? Install LVGL 9.x for a new project. This guide is written against LVGL 9.2, and the LVGL docs currently serve the 9.4 line. LVGL 9 changed the display, input device, button, and screen function names, so LVGL 8 code will not compile against LVGL 9 without changes. Source: LVGL docs and the ElectricalFlux LVGL ESP32-S3 guide.
Why is my LVGL screen blank after upload? Check the backlight first, then run the TFT_eSPI Colour_Test sketch without LVGL. If Colour_Test fails, the problem is wiring or User_Setup.h, not LVGL. If it passes, check lv_conf.h placement and that loop calls lv_timer_handler and lv_tick_inc. Source: our TFT_eSPI setup guide and SmartDocs.
How do I add touch to LVGL on ESP32? Use the XPT2046 touch controller on touch TFT modules. Install the XPT2046_Touchscreen library, start a second SPI bus for the touch chip with its own chip select pin, register an LVGL input device with lv_indev_create, and set a read callback that maps raw touch values to screen pixels. Source: Random Nerd Tutorials.
Can I use LVGL with ESP-IDF instead of Arduino? Yes. Add the esp_lvgl_port component with idf.py add-dependency “espressif/esp_lvgl_port^2.3.0”, or add LVGL directly with idf.py add-dependency “lvgl/lvgl^9.*”. Source: LVGL docs, “Add LVGL to an ESP32 IDF project”.
Sources
- LVGL docs, Adding LVGL to Your Project (LVGL 9.4): https://docs.lvgl.io/master/details/integration/adding-lvgl-to-your-project/index.html
- LVGL docs, Add LVGL to an ESP32 IDF project: https://lvgl.io/docs/open/integration/chip_vendors/espressif/add_lvgl_to_esp32_idf_project
- LVGL blog, ESP32 plus LVGL Quick Start Guide: https://lvgl.io/blog/tutorial-esp32-getting-started
- Random Nerd Tutorials, LVGL with ESP32 TFT Touchscreen, ILI9341 (Arduino), LVGL 9.2: https://randomnerdtutorials.com/lvgl-esp32-tft-touchscreen-display-ili9341-arduino/
- CircuitDigest, Arduino LVGL Tutorial: Build ESP32 GUI Step-by-Step: https://circuitdigest.com/tutorial/getting-started-with-arduino-lvgl
- SmartDocs, ESP32 plus TFT_eSPI plus LVGL Complete Guide: https://smartdocs.solvosync.ca/en/article/arduino-readme-2/
- ElectricalFlux, Getting Started with LVGL ESP32 S3: 8048S043 RGB Display Build and Debug Guide: https://electricalflux.com/mcu-projects/lvgl-esp32-s3-8048s043-rgb-build-debug
- Elecrow Wiki, LVGL Arduino 2.4 inch ESP32 Touchscreen Environment Monitoring and LED Control: https://www.elecrow.com/wiki/2.4-inch-esp32-dispaly-arduino-tutorial.html
- Bodmer TFT_eSPI GitHub repo README: https://github.com/Bodmer/TFT_eSPI
- Quality RC Parts, TFT_eSPI Setup Guide: https://qualityrcparts.com/tft-espi-setup-guide/
- Quality RC Parts, ESP32 Boards with Built-In Displays: TFT vs OLED Compared: https://qualityrcparts.com/esp32-built-in-display-boards-tft-oled-guide/
- Quality RC Parts, OLED vs TFT Display: https://qualityrcparts.com/oled-vs-tft-display/
- Quality RC Parts, How to Choose the Right Display for Arduino or ESP32: https://qualityrcparts.com/which-display-to-buy/
Last updated: 2026-11-21





