TFT_eSPI Setup Guide: Arduino, ESP32, User_Setup.h

TFT_eSPI is the library most ESP32 display projects use, and the one that confuses the most first-time users. It does not ask your sketch which display you wired up. It reads that answer from a setup file at compile time, and if the setup file is wrong, the screen stays white even though the sketch uploads fine.

This guide sets up TFT_eSPI from Bodmer’s GitHub repo for a separate SPI TFT module wired to an ESP32 board: install, wiring, driver pick, the User_Setup.h edit, the first test sketch, and the errors that stop most builds. Every step was checked against the TFT_eSPI README and the User_Setup.h file in the repo.

What is TFT_eSPI, and what do you need before you start?

TFT_eSPI is a feature-rich Arduino IDE graphics and fonts library for 32-bit processors, written by Bodmer. The README says it is targeted at 32-bit processors and performance optimised for RP2040, STM32, ESP8266, and ESP32 types, and that it works with Arduino boards as well but will be slower. On the ESP32 it can use Direct Memory Access (DMA) with SPI displays, and it has built-in support for the XPT2046 touch controller.

The one fact that shapes this whole guide is in the README: the screen controller, the interface pins, and the library configuration settings must be defined inside the library, not in the Arduino sketch. PlatformIO users can define the same settings in platformio.ini instead, covered below.

What you need:

  • An ESP32 board. This guide uses the ESP32 DevKit V1 (30-pin WROOM-32), because its hardware SPI pins are the ones in the library’s own example setup files.
  • A separate SPI TFT module. The worked examples use the 0.96 inch ST7735 module and the 2.4 inch touch ILI9341 module from the store.
  • The Arduino IDE with the ESP32 board package installed. The README says the library requires board package 2.x.x or later.
  • Jumper wires and a breadboard. Keep the SPI wires short: long wires cause signal problems.

How do you install TFT_eSPI in the Arduino IDE?

Open the Library Manager: Sketch, Include Library, Manage Libraries. Search for “TFT_eSPI”, find the entry by Bodmer, and press Install.

Two README warnings apply from the first install. First, a library update overwrites your setup: keep custom setup files in a TFT_eSPI_Setups folder in your Arduino libraries folder, pointed at from User_Setup_Select.h. Second, install the ESP32 board package first, at version 2.x or later, or the library may not compile for your board. PlatformIO users install it with one line in platformio.ini:

lib_deps = bodmer/TFT_eSPI

Source: Lopaka TFT_eSPI guide.

How do you wire a TFT module to an ESP32 DevKit V1?

The QRC TFT modules wire over SPI with 8 pins: GND, VCC, SCL, SDA, RES, DC, CS, and BLK. SCL is the SPI clock (SCLK), SDA is MOSI, RES is reset (RST), DC is data/command, CS is chip select, and BLK is the backlight. The pin numbers below are from the library’s own ESP32 example setup (Setup42_ILI9341_ESP32.h).

Module pin ESP32 DevKit V1 GPIO Library name
GND GND –
VCC 3V3 –
SCL GPIO 18 TFT_SCLK
SDA GPIO 23 TFT_MOSI
MISO / SDO GPIO 19 TFT_MISO
RES GPIO 4 TFT_RST
DC GPIO 2 TFT_DC
CS GPIO 15 TFT_CS
BLK 3V3, or a free GPIO for dimming TFT_BL

Three wiring rules. Power the module at 3.3V, not 5V. The QRC modules run on 3.3V power, and the ESP32 is a 3.3V board, so wire VCC to 3V3. A 5V Arduino Uno needs level shifting; see our logic level shifting guide. Use the hardware SPI pins for clock and data. MOSI 23, MISO 19, and SCLK 18 are the DevKit V1 VSPI pins. CS, DC, and RST can be any free GPIO. Connect MISO even if you think you do not need it. The screen draws without it, but the display ID read and the touch controller need it, and an SD card on the same bus needs all three SPI pins defined explicitly. Backlight: BLK can go straight to 3V3 for always-on backlight. Wire it to a GPIO and define TFT_BL only if the sketch must control it.

Which driver do you pick for your display?

The driver is the chip on the display, not the size of the screen. Two modules the same size can need different drivers, and the wrong driver gives a white screen even with perfect wiring. Read the driver chip name from the store listing first.

Size Resolution Driver Touch Store price
0.96 inch, 2-pack 80 by 160 ST7735 No $13.99
1.3 inch 240 by 240 ST7789 No $11.99
1.44 inch, 2-pack 128 by 128 ST7735 No $20.99
1.8 inch, SD slot 128 by 160 ST7735 No $10.99
2.0 inch 240 by 320 ST7789 No $14.99
2.2 inch, SD slot 240 by 320 ILI9341 No From $18.99
2.4 inch, no touch 320 by 240 ST7789 No $14.99
2.4 inch, touch 240 by 320 ILI9341 Yes $20.99
2.8 inch, touch 240 by 320 ILI9341 Yes $24.99
3.2 inch, touch 240 by 320 ILI9341 Yes $25.49
3.5 inch, touch 480 by 320 ILI9488 Yes $26.99
4.0 inch, touch 480 by 320 ST7796S Yes $29.99

Sizes, resolutions, and drivers follow our TFT LCD displays guide, and prices were verified against the live store on 2026-11-21. The README lists ST7735, ST7789, ILI9341, ILI9488, and ST7796 as supported, and recommends ILI9341 and ST7796 SPI displays as the starting point. If the listing does not name a driver, do not guess: a 2.4 inch module can be ST7789 without touch or ILI9341 with touch.

How do you set up User_Setup.h?

This is the step the whole guide exists for. User_Setup.h is the file inside the TFT_eSPI library folder that names your driver, your screen size, your pins, and your fonts. The library reads it at compile time. The default file ships set up for an ILI9341 display, so ST7735 or ST7789 owners must change it. Find the file in your Arduino libraries folder, under TFT_eSPI.

1. Pick exactly one driver

In Section 1 of the file, uncomment the line for your driver and leave every other driver line commented out. Only one driver may be defined.

For the 0.96 inch module:

#define ST7735_DRIVER      // Define additional parameters below for this display

For a 1.3 inch, 2.0 inch, or 2.4 inch non-touch module:

#define ST7789_DRIVER      // Full configuration option, define additional parameters below for this display

For a 2.2 inch, 2.4 inch touch, 2.8 inch, or 3.2 inch module:

#define ILI9341_DRIVER       // Generic driver for common displays

The default file ships with ILI9341_DRIVER uncommented. If two driver lines are uncommented, the sketch will not compile, or the library will send the wrong init sequence and the screen stays white.

2. Set the screen size

Set TFT_WIDTH and TFT_HEIGHT to your panel’s pixel size: 80 by 160 for the 0.96 inch ST7735 module, 240 by 320 for the 2.4 inch touch ILI9341 module, 240 by 240 for the 1.3 inch ST7789 module.

#define TFT_WIDTH  240
#define TFT_HEIGHT 320

Getting the size wrong does not stop the screen from working, but the drawing will be shifted or cut off.

3. Set the pins

Set the pin defines to match your wiring. The ESP32 example values in the file are MISO 19, MOSI 23, SCLK 18, CS 15, DC 2, and RST 4, which match the wiring table above.

#define TFT_MISO 19
#define TFT_MOSI 23
#define TFT_SCLK 18
#define TFT_CS   15  // Chip select control pin
#define TFT_DC    2  // Data Command control pin
#define TFT_RST   4  // Reset pin (could connect to RST pin)

If your module’s reset pin is tied to the board reset or to 3.3V, set TFT_RST to -1.

4. Check the fonts and the SPI speed

Leave the font lines as they are. You need LOAD_GLCD at minimum; without it, basic text drawing will not compile. The default SPI frequency is 27 MHz; the bundled Setup42 uses 40 MHz. If the display shows noise or tearing, drop the speed to 20 MHz or 10 MHz. Save the file, then recompile and upload: the library reads User_Setup.h at compile time, so every edit needs a fresh compile.

What are the other ways to configure TFT_eSPI?

Editing User_Setup.h is the standard route, but it is not the only one. There are three, and you should pick one and stick to it. Mixing them is a common cause of “it worked yesterday” failures.

Option 1: Edit User_Setup.h. The route above. Simple, and every example sketch then works without changes. The cost is that a library update overwrites the file, so keep a copy in the TFT_eSPI_Setups folder the README suggests, outside the library folder.

Option 2: Use a bundled setup file. Open User_Setup_Select.h in the library folder. Comment out the #include <User_Setup.h> line and uncomment the include for a setup file that matches your board. The repo ships Setup42_ILI9341_ESP32.h for an ESP32 with an SPI ILI9341 display (MISO 19, MOSI 23, SCLK 18, CS 15, DC 2, RST 4, 40 MHz), Setup70b_ESP32_S3_ILI9341.h for the ESP32-S3, Setup70c_ESP32_C3_ILI9341.h for the ESP32-C3, and Setup71_ESP32_S2_ST7789.h for the ESP32-S2 with ST7789. Only one setup include may be active at a time.

Option 3: Define the setup in the sketch or in PlatformIO. If you define USER_SETUP_LOADED before including the library, the library skips User_Setup.h and uses the defines in your sketch instead. The library header TFT_eSPI.h checks for USER_SETUP_LOADED and defines it itself if it is missing, so a sketch that defines it first takes control:

#define USER_SETUP_LOADED
#define ILI9341_DRIVER
#define TFT_WIDTH  240
#define TFT_HEIGHT 320
#define TFT_MOSI 23
#define TFT_MISO 19
#define TFT_SCLK 18
#define TFT_CS   15
#define TFT_DC    2
#define TFT_RST   4
#define SPI_FREQUENCY 40000000
#include <TFT_eSPI.h>
#include <SPI.h>

Source: the USER_SETUP_LOADED check in TFT_eSPI.h and the ElectricalFlux ESP32 graphics guide. PlatformIO users can pass the same defines as build flags instead, which survives library updates. Source: Lopaka TFT_eSPI guide. The in-sketch route keeps the setup with the project, the right choice when two projects use two different displays on one computer.

What is the first sketch to upload?

Run the library’s own test sketch before you write any of your own code. If the test sketch works, the wiring and the setup file are right, and any later problem is in your code.

Open File, then Examples, then TFT_eSPI, then Test and diagnostics, then Colour_Test. Select your ESP32 board and port, and upload. A working screen shows clean colour bands with no noise or tearing.

If Colour_Test runs but the colours look wrong, run the Read_User_Setup example from the same folder. It prints the setup the library actually compiled with to the serial monitor: driver, pins, and SPI frequency.

Once Colour_Test passes, a minimal hello sketch confirms text drawing:

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextSize(2);
  tft.drawString("Hello TFT", 10, 10);
}

void loop() {
}

tft.init() starts the display with the settings from the setup file. If this sketch shows “Hello TFT”, the setup is done.

How do you set up the built-in 1.9 inch TFT board?

Short answer: you do not use this guide for it. The built-in 1.9 inch ST7789 board (ID 17819) is covered in full in our ESP32 boards with built-in displays guide: ST7789 driver at 170 by 320, with CS 5, RST 4, BL 32, and MOSI 23. Follow that guide for that board.

What are the common mistakes?

  • Two drivers uncommented: only one driver define may be active. Two break the compile or send the wrong init sequence.
  • Editing the setup and not recompiling: the library reads User_Setup.h at compile time.
  • Pins in the file do not match the wiring: file and breadboard must agree on every pin.
  • Default ILI9341 setup with an ST7735 or ST7789 module: the default file ships set for ILI9341.
  • A library update wiping the setup: keep your setup in a TFT_eSPI_Setups folder outside the library, or use the in-sketch defines.
  • 5V logic on a 3.3V module: the QRC modules run on 3.3V power. A 5V Uno needs level shifting.
  • Long jumper wires at full SPI speed: shorten the wires or drop SPI_FREQUENCY to 20 MHz or 10 MHz.
  • MISO left unconnected: the screen draws without it, but the display ID read and touch need it.

How do you fix a TFT_eSPI display that does not work?

Check the config before you suspect broken hardware: a white screen usually means the driver or pins in User_Setup.h do not match the board.

The screen stays white after upload. White means the backlight works and the controller never got a valid init sequence. Check the driver line first, then the pins, then the backlight pin, then a lower SPI speed. Sources: Protoship and RoboticsEngineering white screen guides.

The screen stays black. Check the backlight first. A sketch that never turns it on shows nothing even when the code runs. If BLK is wired to a GPIO, the setup must define TFT_BL and the sketch must drive it.

The colours are wrong or inverted. The colour order or the inversion setting does not match the panel. User_Setup.h has TFT_RGB_ORDER (TFT_RGB or TFT_BGR) and TFT_INVERSION_ON / TFT_INVERSION_OFF defines. Swap the colour order define and recompile.

The picture is shifted, cut off, or noisy. The size is wrong, or the SPI speed is too high for the wiring. Check TFT_WIDTH and TFT_HEIGHT, then drop SPI_FREQUENCY to 20 MHz or 10 MHz.

The sketch will not compile. Read the first error, not the last. Two driver defines active, a missing LOAD_GLCD font define, or a board package older than 2.x are the usual causes. An Arduino forum thread also reports TFT_eSPI sketches failing to compile for the ESP32-C6 board; update the board package and the library before changing the code.

The touch panel does not respond. TFT_eSPI has built-in XPT2046 touch support on SPI displays, and the touch chip shares the display SPI bus with its own chip select. Define TOUCH_CS with the touch CS pin: the bundled Setup42 file shows TOUCH_CS 5, commented out by default. Run Test_Touch_Controller to check the touch wiring.

The display works but the SD card on the same bus stops working. The README warns that an SD card on the same SPI bus needs TFT_MISO, TFT_MOSI, and TFT_SCLK defined explicitly in User_Setup.h, even with the default SPI pins. Define all three and recompile.

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 and purchasable.

Shipped fast and securely from our secure facility in Queensbury, NY. QRC ships within the USA only.

Related guides

FAQ

What is TFT_eSPI? TFT_eSPI is a fast Arduino IDE graphics and fonts library for 32-bit processors by Bodmer, optimised for RP2040, STM32, ESP8266, and ESP32. It drives SPI TFT displays and supports the XPT2046 touch controller. Source: TFT_eSPI README on GitHub.

Do I have to edit User_Setup.h to use TFT_eSPI? Yes, in the standard route: the driver, size, pins, and fonts must be defined in the library’s setup file, because the README states they cannot be defined in the Arduino sketch. Alternatives: a bundled setup file, in-sketch defines with USER_SETUP_LOADED, or PlatformIO build flags. Source: TFT_eSPI README.

Which driver do I pick in TFT_eSPI for my display? Pick the driver that matches the chip on your display: ST7735 for the 0.96, 1.44, and 1.8 inch modules; ST7789 for the 1.3, 2.0, and 2.4 inch non-touch modules; ILI9341 for the 2.2, 2.4 touch, 2.8, and 3.2 inch modules; ILI9488 for the 3.5 inch touch; ST7796 for the 4.0 inch touch. Only one driver define may be active. Source: TFT_eSPI README and the QRC TFT displays guide.

Why is my TFT screen white after uploading a TFT_eSPI sketch? White means the backlight works but the controller never got a valid init sequence. Check the driver first, then the pins, then the backlight pin, then a lower SPI speed. Source: Protoship and RoboticsEngineering white screen guides.

Can I use TFT_eSPI with an Arduino Uno? The library targets 32-bit processors and works with Arduino boards but will be slower, per the README. The bigger issue is voltage: the QRC modules run on 3.3V, and a 5V Uno needs level shifting. An ESP32 is the simpler first choice.

Why does my TFT_eSPI setup disappear after a library update? A new copy of the library overwrites User_Setup.h inside the library folder. The README suggests a TFT_eSPI_Setups folder outside the library, or the in-sketch USER_SETUP_LOADED defines or PlatformIO build flags, which survive updates. Source: TFT_eSPI README tips section.

How do I know which setup the library actually compiled with? Run Read_User_Setup from File, Examples, TFT_eSPI, Test and diagnostics. It prints the compiled driver, pins, and SPI frequency to the serial monitor. Source: TFT_eSPI repo examples listing.

Sources

Last updated: 2026-11-21

Change log

  • 2026-11-21: Draft created. Full TFT_eSPI setup procedure from the Bodmer GitHub repo: install, DevKit V1 wiring, driver-selection table for all 12 store TFT sizes, User_Setup.h walkthrough, two alternate configuration routes, Colour_Test first-sketch walkthrough, common mistakes, troubleshooting. Built-in 1.9 inch board covered only as a pointer to post 18364; size selection cross-linked to posts 17851 and 15484, not re-taught.