Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Marcussacapuces91/doc-TFT_eSPI/llms.txt

Use this file to discover all available pages before exploring further.

Every TFT_eSPI journey starts with the same milestone: text on a screen. This page walks through the canonical Hello World sketch line by line, explains what each call does, and shows you the common variations you’ll reach for next — different colors, different fonts, and positioning text with drawString instead of println.
Before uploading any sketch, you must configure User_Setup.h (or select a pre-made file via User_Setup_Select.h) to match your specific display driver, resolution, and SPI pin assignments. The library will not function correctly until that step is complete.

​
The Complete Sketch

Here is the full Hello World sketch exactly as it runs on an ESP32 or ESP8266 with a 160×128 or 240×320 TFT panel: 
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setCursor(0, 0);
  tft.setTextColor(TFT_WHITE);
  tft.setTextSize(2);
  tft.setTextFont(2); // Set the text font to font number 2
  tft.println("Hello World!");
}

void loop() {
  // nothing to do here, just display the "Hello World!" message
}

​
Step-by-Step Walkthrough

1

Include the library and create a display object

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();
Including TFT_eSPI.h pulls in the full driver stack. TFT_eSPI tft = TFT_eSPI() creates the global display instance named tft. All subsequent calls go through this object. The constructor reads pin and driver settings from User_Setup.h at compile time — there are no runtime arguments needed.
2

Initialize the display

tft.init();
tft.init() sends the startup command sequence to the display controller over SPI. It powers on the panel, sets up internal registers, and leaves the display ready to receive drawing commands. Call this once in setup() before any other drawing function.
3

Set the screen rotation

tft.setRotation(1);
TFT_eSPI supports four rotation values — 0 through 3 — each rotating the coordinate system 90° clockwise relative to the previous. Rotation 1 puts the display in landscape orientation (wide side horizontal). Changing this value does not clear the screen; call fillScreen() afterward if needed.
ValueOrientation
0Portrait (default)
1Landscape
2Portrait flipped
3Landscape flipped
4

Clear the screen

tft.fillScreen(TFT_BLACK);
fillScreen() paints every pixel in the given color. Using TFT_BLACK gives a clean black canvas. TFT_eSPI defines a full set of named color constants — TFT_WHITE, TFT_RED, TFT_GREEN, TFT_BLUE, TFT_YELLOW, TFT_CYAN, TFT_MAGENTA, TFT_ORANGE, and more — all encoded as 16-bit RGB565 values.
5

Position the text cursor

tft.setCursor(0, 0);
setCursor(x, y) sets the pixel position where the next print() or println() call begins. The origin (0, 0) is the top-left corner of the screen in the current rotation. The cursor advances automatically after each character is drawn.
6

Set text color

tft.setTextColor(TFT_WHITE);
This single-argument form draws text in TFT_WHITE with a transparent background — pixels behind each character are not overwritten. Pass a second argument to set a solid background fill: tft.setTextColor(TFT_WHITE, TFT_BLACK) draws white glyphs on a black fill, which is essential when overwriting old text (see Text Padding).
7

Set text size

tft.setTextSize(2);
setTextSize(n) scales the active font by integer factor n. Size 1 is the native pixel size of the font; size 2 doubles it; size 3 triples it, and so on. For clean, sharp text, keep to size 1 or 2 — higher integer scaling introduces visible pixel staircase artifacts on small fonts.
8

Select a font

tft.setTextFont(2);
TFT_eSPI ships with several built-in fonts numbered 0 through 8. Font 2 is a clean 16px proportional font well-suited for general labels and messages. Font 0 is the tiny 6×8 bitmap fallback. Smooth anti-aliased (VLCD/GFXFF) fonts are also available but require additional setup.
FontDescription
06×8 Glcd (Adafruit GFX compatible)
18px bitmap
216px smooth
426px smooth
648px digit-only
748px segment-style digits
875px digit-only
9

Print the message

tft.println("Hello World!");
println() renders the string at the current cursor position and then advances the cursor to the start of the next line, exactly like Serial.println(). print() works the same way but does not add a newline. Both accept strings, integers, floats, and other standard Arduino types.

​
Common Variants

​
Using drawString for Precise Positioning

println moves the cursor as a side effect, which makes it awkward when you want to place text at exact pixel coordinates. drawString is the preferred alternative — it accepts explicit x and y coordinates and is unaffected by the cursor state: 
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setTextFont(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);

  // Draw text at pixel-precise coordinates
  tft.drawString("Hello World!", 10, 20);
}

void loop() {}
When using drawString, set a background color with the two-argument form of setTextColor(fg, bg). This ensures the background behind each glyph is cleared, preventing ghosting when the text changes.

​
Different Text Colors

TFT_eSPI’s predefined color constants cover the most common UI colors. You can also construct any 16-bit RGB565 color using the tft.color565(r, g, b) helper: 
// Named color constants
tft.setTextColor(TFT_RED,    TFT_BLACK); tft.drawString("Red text",    10, 20);
tft.setTextColor(TFT_GREEN,  TFT_BLACK); tft.drawString("Green text",  10, 40);
tft.setTextColor(TFT_YELLOW, TFT_BLACK); tft.drawString("Yellow text", 10, 60);
tft.setTextColor(TFT_CYAN,   TFT_BLACK); tft.drawString("Cyan text",   10, 80);

// Custom color from RGB components (r, g, b each 0–255)
uint16_t orange = tft.color565(255, 165, 0);
tft.setTextColor(orange, TFT_BLACK);
tft.drawString("Orange text", 10, 100);

​
Different Fonts

Swap the font number to change the appearance of your text. Remember to enable the required fonts in User_Setup.h — loading unused fonts wastes flash memory: 
tft.setTextFont(1); tft.drawString("Font 1 — tiny 8px", 5, 10);
tft.setTextFont(2); tft.drawString("Font 2 — 16px",     5, 30);
tft.setTextFont(4); tft.drawString("Font 4 — 26px",     5, 55);
Fonts 6, 7, and 8 contain only digit characters (0–9), a colon, and a period. They are designed for large numeric readouts such as clocks or sensor displays and will render blank rectangles for letters.

​
Adapting to Different Display Sizes

Hard-coding pixel coordinates makes sketches fragile when you move to a different panel. Use tft.width() and tft.height() to write code that adapts automatically: 
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);

  int w = tft.width();   // display width in current rotation
  int h = tft.height();  // display height in current rotation

  tft.setTextFont(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextDatum(MC_DATUM); // anchor to Middle-Centre

  // Always centred, regardless of display resolution
  tft.drawString("Hello World!", w / 2, h / 2);
}

void loop() {}
tft.width() and tft.height() return the logical pixel dimensions of the screen in its current rotation, so width > height in landscape and height > width in portrait. Combine them with MC_DATUM (see Text Datum) to centre text perfectly on any display.

Build docs developers (and LLMs) love

Get started for freeTalk to us