Rendering Text and Numbers on TFT Displays with TFT_eSPI

TFT_eSPI inherits from Arduino’s Print class, giving you familiar print() and println() calls alongside a rich set of dedicated text drawing methods. You can choose between the built-in bitmap fonts (numbered 1–8), GFX-compatible fonts loaded at compile time, or smooth anti-aliased TrueType-style fonts loaded at runtime. Text color, background fill, datum alignment, size scaling, wrapping, and padding are all configurable independently, letting you match any display layout requirement.

Text Configuration

Before drawing text you typically call one or more configuration functions. They persist until you change them again.

`setTextColor`

Set the foreground color, and optionally a background fill color.

void setTextColor(uint16_t color);
void setTextColor(uint16_t fgcolor, uint16_t bgcolor, bool bgfill = false);

color / fgcolor

uint16_t

required

Foreground (glyph) color in RGB565.

bgcolor

uint16_t

Background color drawn behind each character cell. Providing this avoids the need to erase old text before redrawing.

bgfill

bool

When true, the background fill extends to cover the full text padding width set by setTextPadding().

tft.setTextColor(TFT_WHITE);                       // White glyphs, transparent background
tft.setTextColor(TFT_WHITE, TFT_BLACK);            // White on black (no flicker on update)
tft.setTextColor(TFT_YELLOW, TFT_BLACK, true);     // Yellow on black, with padding fill

`setTextSize`

Scale the built-in font by an integer multiplier. Size 1 is native resolution; size 2 doubles each pixel.

void setTextSize(uint8_t size);

size

uint8_t

required

Integer scale factor (1 = native, 2 = double, etc.).

tft.setTextSize(2);

`setTextFont`

Select one of the pre-compiled bitmap fonts by number.

void setTextFont(uint8_t font);

font

uint8_t

required

Font number. 0 or 1 selects the built-in GLCD 6×8 font; fonts 2–8 are optional compiled-in fonts.

tft.setTextFont(2);   // Select font 2
tft.setTextFont(0);   // Revert to default GLCD font

`setTextDatum`

Set the reference point (datum) from which text coordinates are interpreted. This replaces the older drawCentreString / drawRightString helpers.

void setTextDatum(uint8_t datum);

Common datum constants:

Constant	Meaning
`TL_DATUM`	Top-left (default)
`TC_DATUM`	Top-center
`TR_DATUM`	Top-right
`ML_DATUM`	Middle-left
`MC_DATUM`	Middle-center
`MR_DATUM`	Middle-right
`BL_DATUM`	Bottom-left
`BC_DATUM`	Bottom-center
`BR_DATUM`	Bottom-right

tft.setTextDatum(MC_DATUM);   // All subsequent text is centered on (x, y)
tft.drawString("Centered", tft.width() / 2, tft.height() / 2, 2);

`setTextWrap`

Enable or disable automatic line wrapping at the right edge, and optionally at the bottom edge.

void setTextWrap(bool wrapX, bool wrapY = false);

wrapX

bool

required

Wrap at the right edge of the display (or active viewport).

wrapY

bool

Wrap at the bottom edge. Defaults to false.

tft.setTextWrap(true);         // Wrap at right edge only
tft.setTextWrap(true, true);   // Wrap at right and bottom

`setTextPadding` and `getTextPadding`

Reserve a fixed-width background fill zone. When updating a number or string that may shrink, this erases leftover pixels from the previous render.

void     setTextPadding(uint16_t x_width);
uint16_t getTextPadding(void);

x_width

uint16_t

required

Width in pixels of the padded fill zone.

tft.setTextPadding(60);    // Always fill 60 px wide, clearing previous content
uint16_t pad = tft.getTextPadding();

Measuring Text

`textWidth`

Return the rendered pixel width of a string in the given font.

int16_t textWidth(const char *string, uint8_t font);
int16_t textWidth(const char *string);
int16_t textWidth(const String& string, uint8_t font);
int16_t textWidth(const String& string);

int w = tft.textWidth("Hello", 2);   // Width in px of "Hello" in font 2

`fontHeight`

Return the height (in pixels) of the current or specified font.

int16_t fontHeight(uint8_t font);
int16_t fontHeight(void);

int h = tft.fontHeight(2);   // Pixel height of font 2
int h2 = tft.fontHeight();   // Pixel height of the currently selected font

Drawing Strings

`drawString`

Draw a string at (x, y) using the current or specified font. Returns the rendered pixel width.

int16_t drawString(const char   *string, int32_t x, int32_t y, uint8_t font);
int16_t drawString(const char   *string, int32_t x, int32_t y);
int16_t drawString(const String& string, int32_t x, int32_t y, uint8_t font);
int16_t drawString(const String& string, int32_t x, int32_t y);

string

const char* / String&

required

The text to render. Accepts both C-string (char[]) and Arduino String objects.

int32_t

required

X coordinate (interpretation depends on setTextDatum).

int32_t

required

Y coordinate.

font

uint8_t

Font number. Omit to use the current font.

tft.drawString("Hello, World!", 10, 30, 2);        // Font 2
tft.drawString("Using current font", 10, 60);      // Current font
String s = "Arduino String";
tft.drawString(s, 10, 90, 4);

`drawCentreString`

drawCentreString is deprecated. Use setTextDatum(TC_DATUM) or setTextDatum(MC_DATUM) with drawString instead.

Draw a string horizontally centered on x.

int16_t drawCentreString(const char   *string, int32_t x, int32_t y, uint8_t font);
int16_t drawCentreString(const String& string, int32_t x, int32_t y, uint8_t font);

Returns the X coordinate of the end of the string.

tft.drawCentreString("Centered", 160, 20, 2);

`drawRightString`

drawRightString is deprecated. Use setTextDatum(TR_DATUM) or setTextDatum(MR_DATUM) with drawString instead.

Draw a string right-justified so that its right edge aligns with x.

int16_t drawRightString(const char   *string, int32_t x, int32_t y, uint8_t font);
int16_t drawRightString(const String& string, int32_t x, int32_t y, uint8_t font);

tft.drawRightString("Right-aligned", 240, 20, 2);

Drawing Characters

`drawChar`

Three overloads let you draw a single character either with explicit color/size arguments, or using the current text settings plus a font number.

void    drawChar(int32_t x, int32_t y, uint16_t c, uint32_t color, uint32_t bg, uint8_t size);
int16_t drawChar(uint16_t uniCode, int32_t x, int32_t y);
int16_t drawChar(uint16_t uniCode, int32_t x, int32_t y, uint8_t font);

int32_t

required

X coordinate.

int32_t

required

Y coordinate.

uint16_t

required

Character code (first overload).

color

uint32_t

required

Glyph color (first overload).

uint32_t

required

Background color (first overload).

size

uint8_t

required

Scale multiplier (first overload).

uniCode

uint16_t

required

Unicode code point (second and third overloads).

font

uint8_t

Font number (third overload).

The second and third overloads return the character width in pixels.

tft.drawChar(10, 10, 'H', TFT_WHITE, TFT_BLACK, 2);  // 'H', explicit colors, size 2
tft.drawChar('A', 40, 10);                             // Unicode 'A', current font/color
tft.drawChar('A', 40, 10, 2);                          // Unicode 'A', font 2

Drawing Numbers

`drawNumber`

Draw a long integer using the specified or current font. Returns the rendered width in pixels.

int16_t drawNumber(long intNumber, int32_t x, int32_t y, uint8_t font);
int16_t drawNumber(long intNumber, int32_t x, int32_t y);

intNumber

long

required

The integer value to display.

int32_t

required

X coordinate.

int32_t

required

Y coordinate.

font

uint8_t

Font number. Omit to use the current font.

tft.drawNumber(42,           10, 10, 4);
tft.drawNumber(1234567890L,  10, 50);

`drawFloat`

Draw a floating-point number with a specified number of decimal places. Returns the rendered width in pixels.

int16_t drawFloat(float floatNumber, uint8_t decimal, int32_t x, int32_t y, uint8_t font);
int16_t drawFloat(float floatNumber, uint8_t decimal, int32_t x, int32_t y);

floatNumber

float

required

The value to display.

decimal

uint8_t

required

Number of decimal places to render.

int32_t

required

X coordinate.

int32_t

required

Y coordinate.

font

uint8_t

Font number. Omit to use the current font.

tft.drawFloat(3.14159, 3, 10, 10, 2);    // "3.142" in font 2
tft.drawFloat(1024.0 / 7.0, 4, 10, 40); // "146.2857" current font

`print()` and `println()`

TFT_eSPI inherits the Arduino Print interface, so any data type that can be converted to a string can be streamed directly to the display at the current cursor position.

void print(val);
void print(val, format);
void println(val);
void println(val, format);

println() appends a newline and advances the cursor to the left edge of the next line. The cursor position is managed internally and advances automatically after each character.

Use tft.setCursor(x, y) or tft.setCursor(x, y, font) to position the cursor before calling print() / println().

Practical Example — `print()` vs `drawString()`

The following sketch demonstrates both approaches side by side on a 240×135 display.

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

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

  // ── Approach 1: print() / println() ──────────────────────────────────────
  // Simple streaming at a fixed cursor, like Serial output.
  tft.setTextFont(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);  // bg color prevents smearing
  tft.setTextSize(1);
  tft.setCursor(0, 0);

  tft.print("Temperature: ");
  tft.print(23.7, 1);                 // float, 1 decimal place
  tft.println(" C");

  tft.print("Humidity:    ");
  tft.print(58);                      // integer
  tft.println(" %");

  tft.println("Status: OK");

  // ── Approach 2: drawString() with datum alignment ─────────────────────────
  // Explicit positioning with alignment control — better for dashboards.
  tft.setTextFont(4);
  tft.setTextColor(TFT_YELLOW, TFT_BLACK);

  // Centered title at the top
  tft.setTextDatum(TC_DATUM);
  tft.drawString("Dashboard", tft.width() / 2, 80, 4);

  // Right-aligned label at bottom-right
  tft.setTextDatum(BR_DATUM);
  tft.drawString("v1.0", tft.width() - 4, tft.height() - 4, 2);

  // ── Updating a value without flicker ─────────────────────────────────────
  tft.setTextFont(2);
  tft.setTextColor(TFT_GREEN, TFT_BLACK);
  tft.setTextDatum(ML_DATUM);
  tft.setTextPadding(tft.textWidth("99999", 2)); // reserve width for max value

  for (int i = 0; i <= 100; i += 10) {
    tft.drawNumber(i, 10, 110, 2);   // old value is erased by padding fill
    delay(200);
  }
}

void loop() {}

Text Datum Reference

Full list of datum constants and alignment examples.

Anti-Aliased Fonts

Smooth TrueType-style fonts with sub-pixel rendering.

Getting Started

Core Concepts

Drawing & Graphics

Advanced Topics

Hardware

Examples

Rendering Text and Numbers on TFT Displays with TFT_eSPI

Text Configuration

`setTextColor`

`setTextSize`

`setTextFont`

`setTextDatum`

`setTextWrap`

`setTextPadding` and `getTextPadding`

Measuring Text

`textWidth`

`fontHeight`

Drawing Strings

`drawString`

`drawCentreString`

`drawRightString`

Drawing Characters

`drawChar`

Drawing Numbers

`drawNumber`

`drawFloat`

`print()` and `println()`

Practical Example — `print()` vs `drawString()`

Text Datum Reference

Anti-Aliased Fonts

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Drawing & Graphics

Advanced Topics

Hardware

Examples

Documentation Index

​Text Configuration

​setTextColor

​setTextSize

​setTextFont

​setTextDatum

​setTextWrap

​setTextPadding and getTextPadding

​Measuring Text

​textWidth

​fontHeight

​Drawing Strings

​drawString

​drawCentreString

​drawRightString

​Drawing Characters

​drawChar

​Drawing Numbers

​drawNumber

​drawFloat

​print() and println()

​Practical Example — print() vs drawString()

Text Datum Reference

Anti-Aliased Fonts

Build docs developers (and LLMs) love

Text Configuration

`setTextColor`

`setTextSize`

`setTextFont`

`setTextDatum`

`setTextWrap`

`setTextPadding` and `getTextPadding`

Measuring Text

`textWidth`

`fontHeight`

Drawing Strings

`drawString`

`drawCentreString`

`drawRightString`

Drawing Characters

`drawChar`

Drawing Numbers

`drawNumber`

`drawFloat`

`print()` and `println()`

Practical Example — `print()` vs `drawString()`