TFT_eSPI Text Rendering, Font, and String API Reference

TFT_eSPI provides two complementary approaches to displaying text. The print() / println() stream interface (inherited from Arduino’s Print class) advances a cursor automatically, while the explicit drawString(), drawNumber(), and drawFloat() family position output using a configurable datum point. Font selection, colour, size, alignment, wrapping, and UTF-8 decoding are all controllable at runtime. Built-in fonts are numbered 1–8 (fonts 4, 6, 7, and 8 are Run Length Encoded), and GFX free fonts can be loaded with setFreeFont().

print() / println() — Arduino Print Stream

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

Inherited from the Arduino Print base class. Renders any printable value at the current cursor position and advances the cursor. println() adds a newline, moving the cursor to the left edge of the next line.

val

any

The value to render. Accepts String, char*, int, float, double, etc.

format

int

Optional format specifier (e.g. DEC, HEX, BIN, or decimal places for floats).

tft.setCursor(10, 20);
tft.setTextColor(TFT_WHITE, TFT_BLACK);
tft.setTextSize(2);
tft.println("Hello, World!");
tft.print("Value: ");
tft.println(42);

drawString() — Draw String at Position

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)

Draws a string at (x, y) using the specified font (or the current font if omitted). The position is interpreted relative to the current text datum set by setTextDatum().

string

const char* or String&

The text to render. Accepts both char[] and Arduino String types.

int32_t

X coordinate (interpreted via the current text datum).

int32_t

Y coordinate (interpreted via the current text datum).

font

uint8_t

Font number (1–8). If omitted the current font is used.

Returns: int16_t — rendered string width in pixels.

tft.setTextDatum(MC_DATUM); // centre-centre
tft.drawString("Hello!", tft.width() / 2, tft.height() / 2, 4);

drawCentreString() — Centre-Justified String

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)

Draws a string horizontally centred at x-coordinate x.

Deprecated. Use setTextDatum(TC_DATUM) combined with drawString() instead.

string

const char* or String&

Text to render.

int32_t

X coordinate of the horizontal centre of the string.

int32_t

Y coordinate of the top of the string.

font

uint8_t

Font number (1–8).

Returns: int16_t — x coordinate at the end of the rendered text.

tft.drawCentreString("Centred", 160, 10, 2);

drawRightString() — Right-Justified String

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)

Draws a string right-justified so the rightmost character ends at x-coordinate x.

Deprecated. Use setTextDatum(TR_DATUM) combined with drawString() instead.

string

const char* or String&

Text to render.

int32_t

X coordinate of the right edge of the string.

int32_t

Y coordinate of the top of the string.

font

uint8_t

Font number (1–8).

Returns: int16_t — rendered string width in pixels.

tft.drawRightString("Right!", 319, 10, 2);

drawChar() — Draw Single Character

// GLCD / GFX font overload
void drawChar(int32_t x, int32_t y, uint16_t c,
              uint32_t color, uint32_t bg, uint8_t size)

// Current font, current colours
int16_t drawChar(uint16_t uniCode, int32_t x, int32_t y)

// Explicit font number
int16_t drawChar(uint16_t uniCode, int32_t x, int32_t y, uint8_t font)

Renders a single character. The first overload mirrors the Adafruit GFX interface and accepts explicit foreground/background colours and a pixel-doubling size. The second and third overloads accept a Unicode code point and use the current text colour settings.

int32_t

X coordinate for the character top-left corner.

int32_t

Y coordinate for the character top-left corner.

uint16_t

Character code (ASCII or Unicode glyph).

color

uint32_t

Foreground colour (overload 1 only).

uint32_t

Background colour (overload 1 only).

size

uint8_t

Size multiplier (overload 1 only).

uniCode

uint16_t

Unicode code point to render (overloads 2 & 3).

font

uint8_t

Font number (overload 3 only).

Returns (overloads 2 & 3): int16_t — character width in pixels. Overload 1 returns void.

tft.drawChar(10, 10, 'A', TFT_WHITE, TFT_BLACK, 2); // GFX style
tft.drawChar('H', 50, 10, 4);                        // explicit font 4

drawNumber() — Draw Integer

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)

Draws a long integer at the specified position. The position is subject to the current text datum. Compatible with setTextPadding() to erase previously displayed values.

intNumber

long

Integer value to display.

int32_t

X coordinate.

int32_t

Y coordinate.

font

uint8_t

Font number. If omitted the current font is used.

Returns: int16_t — rendered text width in pixels.

tft.setTextDatum(MR_DATUM);
tft.drawNumber(millis() / 1000, 200, 120, 4); // right-aligned elapsed seconds

drawFloat() — Draw Floating-Point Number

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)

Draws a floating-point number with a specified number of decimal places. The position respects the current text datum.

floatNumber

float

Float value to display.

decimal

uint8_t

Number of decimal places to render (0–9).

int32_t

X coordinate.

int32_t

Y coordinate.

font

uint8_t

Font number. If omitted the current font is used.

Returns: int16_t — rendered text width in pixels.

float temperature = 23.75f;
tft.drawFloat(temperature, 2, 120, 80, 4); // "23.75"

setTextColor() — Set Text Colour

// Transparent background (foreground only)
void setTextColor(uint16_t color)

// Opaque background
void setTextColor(uint16_t fgcolor, uint16_t bgcolor, bool bgfill = false)

Sets the text foreground colour. The second overload also sets a background colour that is painted behind each character. When bgfill is true the background is also extended across the full padding width.

color

uint16_t

Text foreground colour (transparent background overload).

fgcolor

uint16_t

Foreground (text) colour.

bgcolor

uint16_t

Background colour painted behind each character.

bgfill

bool

If true, fill the full padding width with bgcolor. Default false.

tft.setTextColor(TFT_WHITE);               // white text, transparent background
tft.setTextColor(TFT_YELLOW, TFT_BLACK);   // yellow on black

setTextSize() — Set Font Size Multiplier

void setTextSize(uint8_t size)

Sets an integer pixel-doubling multiplier applied to all subsequent text rendering. Size 1 is native resolution; size 2 doubles both width and height, etc.

size

uint8_t

Size multiplier (1–7). Each step adds 8 pixels to the character height: 1 = 8px, 2 = 16px, 3 = 24px, 4 = 32px, …

tft.setTextSize(1); // native
tft.setTextSize(3); // 3× enlarged

setTextFont() — Select Built-In Font

void setTextFont(uint8_t font)

Selects the active built-in font by number for all subsequent print() and drawString() calls. Fonts 1–3 are proportional GLCD bitmaps; fonts 4, 6, 7, and 8 are Run Length Encoded large fonts. Font 0 selects the GLCD default.

font

uint8_t

Font number (0–8). Values outside the range of loaded fonts are ignored.

tft.setTextFont(4); // large RLE font
tft.drawString("Big Text", 10, 10);

setFreeFont() — Select GFX Free Font

void setFreeFont(const GFXfont *f = NULL)

Loads an Adafruit GFX-compatible proportional font. Pass NULL (or call with no argument) to revert to the built-in font. Requires the LOAD_GFXFF option to be set in User_Setup.h.

const GFXfont *

Pointer to a GFXfont structure (typically a PROGMEM constant). NULL reverts to the built-in GLCD font.

#include <Fonts/FreeSansBold12pt7b.h>
tft.setFreeFont(&FreeSansBold12pt7b);
tft.drawString("Free Font!", 10, 30);
tft.setFreeFont(NULL); // back to built-in

setTextDatum() — Set Text Alignment Datum

void setTextDatum(uint8_t datum)

Sets the reference point used to position text. The (x, y) coordinate passed to draw functions is mapped to this datum point on the text bounding box.

datum

uint8_t

A datum constant. Key values: TL_DATUM (0, default), TC_DATUM (1), TR_DATUM (2), ML_DATUM (3), MC_DATUM (4), MR_DATUM (5), BL_DATUM (6), BC_DATUM (7), BR_DATUM (8), L_BASELINE (9), C_BASELINE (10), R_BASELINE (11).

tft.setTextDatum(MC_DATUM);
tft.drawString("Centred", tft.width() / 2, tft.height() / 2, 4);

getTextDatum() — Read Current Datum

uint8_t getTextDatum(void)

Returns the currently active text datum value. Returns: uint8_t — current datum constant (see setTextDatum()).

uint8_t d = tft.getTextDatum();

setTextPadding() — Set Overwrite Padding Width

void setTextPadding(uint16_t x_width)

Defines a pixel width that is always cleared to the background colour when drawing text. This prevents stale characters from remaining visible when a shorter string overwrites a longer one.

x_width

uint16_t

Padding width in pixels. The background colour fills from the end of the rendered string up to this total width. Set to 0 to disable.

tft.setTextPadding(120); // always clear 120px worth of background
tft.drawString(String(sensorValue), 10, 50, 4);

getTextPadding() — Read Current Padding

uint16_t getTextPadding(void)

Returns the currently active padding width. Returns: uint16_t — current padding width in pixels.

setTextWrap() — Configure Text Wrapping

void setTextWrap(bool wrapX, bool wrapY = false)

Controls whether print() / println() wraps text at the right edge and optionally at the bottom edge of the display.

wrapX

bool

If true, text wraps to the next line when reaching the right edge.

wrapY

bool

If true, text wraps back to the top when reaching the bottom edge. Default false.

tft.setTextWrap(true, false); // wrap horizontally, not vertically
tft.setCursor(0, 0);
tft.print("This long string will wrap at the display edge.");

textWidth() — Measure String Width

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)

Returns the pixel width of a string if rendered with the specified (or current) font without actually drawing it. Useful for layout calculations.

string

const char* or String&

The string to measure.

font

uint8_t

Font number. If omitted the current font is used.

Returns: int16_t — string width in pixels.

int16_t w = tft.textWidth("Hello", 4);
tft.drawString("Hello", (tft.width() - w) / 2, 10, 4); // manual centering

fontHeight() — Measure Font Height

int16_t fontHeight(uint8_t font)
int16_t fontHeight(void)

Returns the pixel height of the specified font (or the current font).

font

uint8_t

Font number. If omitted the current font is used.

Returns: int16_t — font height in pixels.

int16_t lineH = tft.fontHeight(4);

decodeUTF8() — UTF-8 Byte Decoder

uint16_t decodeUTF8(uint8_t *buf, uint16_t *index, uint16_t remaining)
uint16_t decodeUTF8(uint8_t c)

Decodes UTF-8 encoded byte sequences into Unicode code points. The first overload processes a buffer; the second processes a single byte through the library’s internal state machine (used by the write() stream path).

buf

uint8_t *

Pointer to a UTF-8 encoded byte buffer.

index

uint16_t *

Current position within the buffer; incremented by the decoder.

remaining

uint16_t

Number of bytes remaining in the buffer.

uint8_t

Single UTF-8 byte to feed into the stream decoder.

Returns: uint16_t — decoded Unicode code point, or 0 if the sequence is incomplete.

setAttribute() / getAttribute() — Library Feature Flags

void    setAttribute(uint8_t id = 0, uint8_t a = 0)
uint8_t getAttribute(uint8_t id = 0)

Enable or disable optional library features at runtime.

uint8_t

Feature identifier:

CP437_SWITCH (1) — enable/disable CP437 GLCD font error correction
UTF8_SWITCH (2) — enable/disable UTF-8 decoding in the write() stream (on by default)
PSRAM_ENABLE (3) — enable/disable PSRAM use for sprites and internal buffers

uint8_t

Value to set: true / 1 to enable, false / 0 to disable.

getAttribute() Returns: uint8_t — current value of the specified attribute.

tft.setAttribute(UTF8_SWITCH, true);   // enable UTF-8 (default)
tft.setAttribute(CP437_SWITCH, true);  // enable CP437 corrections
tft.setAttribute(PSRAM_ENABLE, true);  // enable PSRAM for sprites

uint8_t utf8State = tft.getAttribute(UTF8_SWITCH);

TFT_eSPI Class

TFT_eSPI_Button Class

Constants & Types

TFT_eSPI Text Rendering, Font, and String API Reference

print() / println() — Arduino Print Stream

drawString() — Draw String at Position

drawCentreString() — Centre-Justified String

drawRightString() — Right-Justified String

drawChar() — Draw Single Character

drawNumber() — Draw Integer

drawFloat() — Draw Floating-Point Number

setTextColor() — Set Text Colour

setTextSize() — Set Font Size Multiplier

setTextFont() — Select Built-In Font

setFreeFont() — Select GFX Free Font

setTextDatum() — Set Text Alignment Datum

getTextDatum() — Read Current Datum

setTextPadding() — Set Overwrite Padding Width

getTextPadding() — Read Current Padding

setTextWrap() — Configure Text Wrapping

textWidth() — Measure String Width

fontHeight() — Measure Font Height

decodeUTF8() — UTF-8 Byte Decoder

setAttribute() / getAttribute() — Library Feature Flags

Build docs developers (and LLMs) love

TFT_eSPI Class

TFT_eSPI_Button Class

Constants & Types

Documentation Index

​print() / println() — Arduino Print Stream

​drawString() — Draw String at Position

​drawCentreString() — Centre-Justified String

​drawRightString() — Right-Justified String

​drawChar() — Draw Single Character

​drawNumber() — Draw Integer

​drawFloat() — Draw Floating-Point Number

​setTextColor() — Set Text Colour

​setTextSize() — Set Font Size Multiplier

​setTextFont() — Select Built-In Font

​setFreeFont() — Select GFX Free Font

​setTextDatum() — Set Text Alignment Datum

​getTextDatum() — Read Current Datum

​setTextPadding() — Set Overwrite Padding Width

​getTextPadding() — Read Current Padding

​setTextWrap() — Configure Text Wrapping

​textWidth() — Measure String Width

​fontHeight() — Measure Font Height

​decodeUTF8() — UTF-8 Byte Decoder

​setAttribute() / getAttribute() — Library Feature Flags

Build docs developers (and LLMs) love

print() / println() — Arduino Print Stream

drawString() — Draw String at Position

drawCentreString() — Centre-Justified String

drawRightString() — Right-Justified String

drawChar() — Draw Single Character

drawNumber() — Draw Integer

drawFloat() — Draw Floating-Point Number

setTextColor() — Set Text Colour

setTextSize() — Set Font Size Multiplier

setTextFont() — Select Built-In Font

setFreeFont() — Select GFX Free Font

setTextDatum() — Set Text Alignment Datum

getTextDatum() — Read Current Datum

setTextPadding() — Set Overwrite Padding Width

getTextPadding() — Read Current Padding

setTextWrap() — Configure Text Wrapping

textWidth() — Measure String Width

fontHeight() — Measure Font Height

decodeUTF8() — UTF-8 Byte Decoder

setAttribute() / getAttribute() — Library Feature Flags