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.

TFT_eSPI offers a rich text rendering system that covers everything from compact GLCD bitmaps to smooth anti-aliased fonts loaded from flash. Alongside font selection, the library provides a datum system — a set of named reference points — that lets you anchor text to any corner, edge, or centre of its bounding box without manually measuring string widths.

​
Built-in Bitmap Fonts

TFT_eSPI includes eight built-in bitmap fonts selectable by number. Select one with setTextFont(n) or by passing the font number directly to drawing functions: 
void TFT_eSPI::setTextFont(uint8_t f);  // f = 1 to 8
Fonts 4, 6, 7, and 8 are stored as Run Length Encoded (RLE) bitmaps to reduce the FLASH footprint compared to uncompressed fonts.
Font NumberDescriptionApproximate HeightEncoding
1GLCD font (Adafruit GFX compatible)8 pxRaw
2Small proportional font16 pxRaw
4Medium proportional font26 pxRLE
6Large digit font (0–9 and : only)48 pxRLE
77-segment style digit font48 pxRLE
8Large digit font (0–9 and : only)75 pxRLE
Fonts 6, 7, and 8 only include the digit characters 0–9 plus the colon :. Attempting to render letters with these fonts produces blank output. Use them for clock faces, counters, and numeric readouts.

​
Hello World with Font 2

#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);    // 2× scale multiplier applied on top of the font
  tft.setTextFont(2);    // Select the 16 px built-in font
  tft.println("Hello World!");
}

void loop() {}

​
GFX Free Fonts

In addition to the numbered fonts, TFT_eSPI supports the full Adafruit GFX proportional font collection via setFreeFont(). Free fonts are stored as const GFXfont structures in PROGMEM and offer smooth proportional rendering across a wide range of sizes. 
#include <TFT_eSPI.h>
#include <Fonts/FreeSans12pt7b.h>   // Include the desired GFX font header

TFT_eSPI tft = TFT_eSPI();

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

  tft.setFreeFont(&FreeSans12pt7b);      // Activate the GFX free font
  tft.setTextColor(TFT_YELLOW, TFT_BLACK);
  tft.drawString("Free Font!", 10, 30);

  tft.setTextFont(0);  // Pass 0 (or NULL) to return to the GLCD font
}

void loop() {}
GFX font headers live in the Fonts/ subdirectory of the TFT_eSPI library. Pass NULL or call setTextFont(0) to deactivate a free font and return to the numbered font system.

​
Smooth (Anti-aliased) Fonts

When #define SMOOTH_FONT is enabled in User_Setup.h, TFT_eSPI can load VLW format smooth fonts from SPIFFS or LittleFS. These fonts use anti-aliasing for crisp rendering at any size. 
// In User_Setup.h:
//   #define SMOOTH_FONT

tft.loadFont("NotoSans-Regular20");   // Load font file from filesystem
tft.setTextColor(TFT_WHITE, TFT_BLACK);
tft.drawString("Smooth text", 10, 50);
tft.unloadFont();                      // Free memory when done
Smooth fonts require SMOOTH_FONT to be defined at compile time and a filesystem (SPIFFS or LittleFS) pre-loaded with the .vlw font files generated by the Processing sketch bundled with the library.

​
Text Datum Constants

A datum defines the reference point on the text bounding box that is pinned to the (x, y) coordinate you pass to drawString(). By default TFT_eSPI uses TL_DATUM (top-left), meaning (x, y) locates the top-left corner of the first character. Set the active datum with: 
void TFT_eSPI::setTextDatum(uint8_t d);

​
Full Datum Table

ConstantValueReference Point
TL_DATUM0Top left (default)
TC_DATUM1Top centre
TR_DATUM2Top right
ML_DATUM3Middle left
CL_DATUM3Centre left, same as ML_DATUM
MC_DATUM4Middle centre
CC_DATUM4Centre centre, same as MC_DATUM
MR_DATUM5Middle right
CR_DATUM5Centre right, same as MR_DATUM
BL_DATUM6Bottom left
BC_DATUM7Bottom centre
BR_DATUM8Bottom right
L_BASELINE9Left character baseline (line the ‘A’ character would sit on)
C_BASELINE10Centre character baseline
R_BASELINE11Right character baseline
The three baseline datums (L_BASELINE, C_BASELINE, R_BASELINE) pin the coordinate to the line that capital letters like A sit on, making it straightforward to vertically align text with graphical elements at a known Y position.

​
Datum Usage Example

The following sketch demonstrates several datum constants in a single setup: 
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.begin();
  tft.setRotation(3);           // Landscape flipped
  tft.fillScreen(TFT_BLACK);

  int cx = tft.width()  / 2;   // Screen centre X
  int cy = tft.height() / 2;   // Screen centre Y

  // Draw a crosshair at centre for reference
  tft.drawFastHLine(0, cy, tft.width(),  TFT_DARKGREY);
  tft.drawFastVLine(cx, 0, tft.height(), TFT_DARKGREY);

  // Middle-centre: text is centered on the crosshair
  tft.setTextDatum(MC_DATUM);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.drawString("Hello, World!", cx, cy, 4);

  // Top-left: pin top-left of text to screen origin
  tft.setTextDatum(TL_DATUM);
  tft.setTextColor(TFT_CYAN, TFT_BLACK);
  tft.drawString("Top left corner!", 0, 0, 2);

  // Bottom-right: pin bottom-right of text to screen corner
  tft.setTextDatum(BR_DATUM);
  tft.setTextColor(TFT_YELLOW, TFT_BLACK);
  tft.drawString("Bottom right!", tft.width(), tft.height(), 2);
}

void loop() {
  // Read back the active datum at any time
  uint8_t d = tft.getTextDatum();
  // d == BR_DATUM (8) — the last datum set in setup()
  delay(1000);
}
1

Choose a font

Call setTextFont(n) for built-in fonts, setFreeFont(&font) for GFX fonts, or load a smooth font from the filesystem.
2

Set the datum

Call setTextDatum(d) with one of the 12 datum constants to define which part of the text bounding box the coordinates anchor to.
3

Set text color

Use setTextColor(fg) or setTextColor(fg, bg) to define foreground and optional background fill colors.
4

Draw with drawString()

Pass the string, x, y, and optionally the font number to drawString(). The datum you set determines exactly where (x, y) maps on the rendered text.

Build docs developers (and LLMs) love

Get started for freeTalk to us