The Adafruit_CircuitPython_Display_Text library allows you to easily add text to your displayio based CircuitPython projects. If you have no prior experience with displayio, you should check out the Displayio Basics Guide first to learn the basic concepts.

This guide will show you how to install the library and go over all of the features and what they do.

Other Helpful Resources

• Display_Text docs page
• Repository Example scripts
• Example scripts from this guide
• Bitmap_Font library

Parts

Here are some displays that work well with CircuitPython and the displayio library:

You should install the latest version of CircuitPython for your device as well as the newest versions of the libraries which will be used.

CircuitPython

The topics covered in this guide apply to many different devices. Follow the instructions here to get the newest version of for your device. Find the latest version for your device at circuitpython.org/downloads.

Libraries

The adafruit_display_text library currently has two different types of label functions in it. This guide goes over those label functions and the differences between them. If you are less concerned about the details and just want to know which to use for your new project, go with BitmapLabel.

Label

This is the original Label class. Each glyph within the text is stored in its own Bitmap and TileGrid objects, and those all get put into a single Group object. In prior versions of CircuitPython there was a parameter max_glyphs that enforced a limitation in the underlying Group that limited the number of items in the Group. In CircuitPython 7.0.0 this limitation has been removed from Group and therefore also no longer applies to Label.

If you set a background_color, then the background will get its own TileGrid and Bitmap as well. The diagram above depicts a Label with no background Bitmap in it.

BitmapLabel

This is a newer class that was introduced more recently after many features were added into the original Label class. In the BitmapLabel, all of the glyphs are stored inside of a single Bitmap and TileGrid. This tends to result in lower memory usage, especially for long strings.

BitmapLabel typically will use a little bit less RAM -- it can be helpful sometimes in larger projects to switch from Label to BitmapLabel to save more RAM for your projects other needs.

OutlinedLabel

Starting with the release version 3.1.0 the Adafruit_Display_Text Library supports an OutlinedLabel which lets you make text with an outline stroke of a specified size and color.

text_area = OutlinedLabel(
    terminalio.FONT,
    text="Outlined\nLabel",
    color=0xFF00FF,
    outline_color=0x00FF00,
    outline_size=1,
    scale=5,
)

1
2
3
4
5
6
7
8

text_area = OutlinedLabel(
    terminalio.FONT,
    text="Outlined\nLabel",
    color=0xFF00FF,
    outline_color=0x00FF00,
    outline_size=1,
    scale=5,
)

Scrolling Label

Starting with the release version 2.22.0 the Adafruit_Display_Text library supports ScrollingLabel. The ScrollingLabel class is a label that can have a specified maximum number of characters showing at a time and will scroll through a larger message, like a marquee.

The ScrollingLabel depicted above is initialized with the following code:

text = "Hello world CircuitPython scrolling label"
my_scrolling_label = ScrollingLabel(
    terminalio.FONT, 
    text=text, 
    max_characters=20, 
    animate_time=0.1, 
    scale=2
)
while True:
    my_scrolling_label.update()

1
2
3
4
5
6
7
8
9
10

text = "Hello world CircuitPython scrolling label"
my_scrolling_label = ScrollingLabel(
    terminalio.FONT, 
    text=text, 
    max_characters=20, 
    animate_time=0.1, 
    scale=2
)
while True:
    my_scrolling_label.update()

Advanced Color Masking 

There are a few different ways to place your text with display_text labels. All of these settings are available for both Label and BitmapLabel.

x, y coordinates

 

The label can be placed using x, y coordinates. The default origin is located on the far left horizontally, and half the height vertically as shown in the image above.

Descenders

Many fonts have glyphs with descenders that drop down below the baseline. This image illustrates some of them:

Anchored Positioning

If you'd like more precise control over the placement of your text, you can use anchor_point and anchored_position instead of x and y coordinates. With this method, you can set the origin point anywhere you want within your Label. It's particularly useful for centering text within the display, or aligning it to the right edge of the display.

anchor_point is a tuple containing two float values. This is the point that your Label will get positioned relative to. 0.0 being left and top, and 1.0 being right and bottom with values between representing their location within the rectangle that makes up your label. The default is (0.0, 0.0) which is the top left corner.

There are many parameters and properties you can use to control the way your text looks. This page will list them and show examples of each. All of these settings may be used on both BitmapLabel and Label.

Custom fonts are achieved with the Adafruit_Circuitpython_Bitmap_Font library. There are two types of custom font files supported: pcf and bdf. You can find font files online and use converters to get them to the correct formats for use with display text labels. This guide covers the process:

Sometimes when you make labels, you will want to change the text that they are displaying at some point after they've been initialized. A common example of this would be showing the value being read from a sensor, then updating it as you make new readings from the sensor.

Basic Example

This example initializes a label before the main loop begins. Then inside the main loop it updates the text property on the label with the value it gets from time.monotonic(). This example can be run on any CircuitPython device with a built-in display. 

Updating the text property will change what appears in the label on the display.

In the example below, click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file. Extract the contents of the zip file, open the directory updating_text_example/ and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your CIRCUITPY drive.

Your CIRCUITPY drive should now look similar to the following image:

# SPDX-FileCopyrightText: 2021 Tim C, written for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
This examples shows how to update your label with new text.
"""
import time
import board
import displayio
import terminalio
from adafruit_display_text import label

# built-in display
display = board.DISPLAY

# Make the display context
main_group = displayio.Group()
display.root_group = main_group

# create the label
updating_label = label.Label(
    font=terminalio.FONT, text="Time Is:\n{}".format(time.monotonic()), scale=2
)

# set label position on the display
updating_label.anchor_point = (0, 0)
updating_label.anchored_position = (20, 20)

# add label to group that is showing on display
main_group.append(updating_label)

# Main loop
while True:

    # update text property to change the text showing on the display
    updating_label.text = "Time Is:\n{}".format(time.monotonic())

    time.sleep(1)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# SPDX-FileCopyrightText: 2021 Tim C, written for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
This examples shows how to update your label with new text.
"""
import time
import board
import displayio
import terminalio
from adafruit_display_text import label

# built-in display
display = board.DISPLAY

# Make the display context
main_group = displayio.Group()
display.root_group = main_group

# create the label
updating_label = label.Label(
    font=terminalio.FONT, text="Time Is:\n{}".format(time.monotonic()), scale=2
)

# set label position on the display
updating_label.anchor_point = (0, 0)
updating_label.anchored_position = (20, 20)

# add label to group that is showing on display
main_group.append(updating_label)

# Main loop
while True:

    # update text property to change the text showing on the display
    updating_label.text = "Time Is:\n{}".format(time.monotonic())

    time.sleep(1)

What NOT To Do

Be careful not to create new labels infinitely in the main loop. It can lead to a Memory Error caused by making too many new labels.

# SPDX-FileCopyrightText: 2020 Tim C, written for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
This examples shows the WRONG way change your displayed text in the main loop.
"""
import time
import board
import displayio
import terminalio
from adafruit_display_text import label

# built-in display
display = board.DISPLAY

# Make the display context
main_group = displayio.Group()
display.root_group = main_group


# Main loop
while True:
    
    # You should not create labels in an unrestriced manner like this.
    #
    # DONT DO THIS!!!
    #
    new_label = label.Label(
        font=terminalio.FONT, 
        text="Time Is:\n{}".format(time.monotonic()),
        scale=2,
        x=20, y=50
    )
    main_group.append(new_label)
    main_group.pop(0)
    
    time.sleep(1)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# SPDX-FileCopyrightText: 2020 Tim C, written for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
This examples shows the WRONG way change your displayed text in the main loop.
"""
import time
import board
import displayio
import terminalio
from adafruit_display_text import label

# built-in display
display = board.DISPLAY

# Make the display context
main_group = displayio.Group()
display.root_group = main_group


# Main loop
while True:
    
    # You should not create labels in an unrestriced manner like this.
    #
    # DONT DO THIS!!!
    #
    new_label = label.Label(
        font=terminalio.FONT, 
        text="Time Is:\n{}".format(time.monotonic()),
        scale=2,
        x=20, y=50
    )
    main_group.append(new_label)
    main_group.pop(0)
    
    time.sleep(1)