Objects
A label is made of objects. This page covers each kind, then the things they all share: position, size, rotation, and order.
Settings every object shares#
| Setting | Meaning |
|---|---|
| X, Y | Distance of the object's top-left corner from the label's top-left corner, in millimeters. |
| W, H | Width and height in millimeters. |
| Rotation | Clockwise degrees, any value including fractions. The X and Y of a rotated object describe the box that contains it. |
| Forward / Backward | Move the object up or down one layer. Objects higher in the stack cover those below. |
| Rotate 90°, Flip horizontally, Flip vertically | A quarter turn clockwise, and mirror images. The flip buttons stay pressed while a flip is on, and the flip is applied before the rotation. |
| Center on label | Centers the object horizontally or vertically on the label. |
| Lock position and size | Protects the object from being moved, resized, rotated, or deleted on the canvas. Its other settings stay editable only after you unlock it. |
| Duplicate | Makes a copy of the object (Ctrl+D). |
| Delete | Removes it (Delete). |
Copy and paste (Ctrl+C, Ctrl+V) work on one or several selected objects. Everything can be undone with Ctrl+Z.
Text#
Click the T tool to add a text box that says Your text. Edit it in the properties panel. The address tool adds a three-line block ready for a name, street, and city.
| Setting | Meaning |
|---|---|
| Object text box | The text. It can have several lines; press Enter for a new line. |
| Font size | In points, from 3 to 300. Larger numbers make taller letters. |
| Bold | Heavier letters. Good for thermal printing, which can make thin text faint. |
| Italic | Slanted letters. |
| Inverse | White letters on a black box that fills the object. |
| Font | The list has three groups. See Fonts. |
| Left / Center / Right | Alignment inside the box. |
| Save to address book | Keeps the text, named after its first line. See Address book below. |
| Wrap long lines | Breaks lines at spaces so they fit the box width. A single word longer than the box is broken as well. |
| Shrink to fit the box | Makes the text smaller, down to 3 pt, until all of it fits inside the box. |
| Line spacing | A multiplier from 0.5 to 3 for the space between lines (1 to start). |
Fonts#
Select a text object and click its font button (it shows the current font) to open Choose a font. Each font's name is drawn in that font, so you can see how it looks, with its plain name on the right. Type in Search fonts to narrow the list by name, then click a font to use it; the window closes. Esc or the window's close button closes it without changing the font. The list has three groups:
| Group | Fonts | On another computer |
|---|---|---|
| Built in | Default (DejaVu Sans), and five fonts chosen for labels: Condensed (fits more text on a line, for long addresses and product names), Monospace (every character the same width, for SKUs, order numbers, and serials), Serif (a classic look for name labels, jars, and gifts), Headline (tall and heavy, for words like FRAGILE or SALE), and Rounded (a friendly look for price tags). | They come with ThermalPrint, so a design prints the same on every computer. |
| Your fonts | Fonts you added with the T button next to the list, from a .ttf or .otf file. They are copied into ThermalPrint's fonts folder. | Add the same font file there too. |
| On this computer | The fonts installed on your computer. Type in Search fonts to find one by name. | Install the same font there too. |
New text uses the font you chose last. ThermalPrint remembers the last font you picked (even after you close it), and new text, addresses, and address book entries start with it; until you pick one, that is Default (DejaVu Sans). If that font is no longer installed, new text uses the default font. The font window always opens at the text's current font, highlighted, so you can see what is in use and pick a neighbor.
A design stores only the font's name. When a font from Your fonts or On this computer is chosen, a note under the list reminds you that another computer needs it installed. If a design's font is missing, the default font is used and a note says so.
Bold works with the default font, with Condensed, Monospace, and Serif, and with a computer font whose family has a Bold style. Headline and Rounded have one weight; for your own fonts, add a bold file.
Some installed fonts can change their weight or width (variable fonts). ThermalPrint draws them in their standard style, so each is listed once. Font collections (.ttc), bitmap fonts, and fonts made only for other writing systems (such as Arabic or Thai, which have no Latin letters) are not listed.
Unless you tick Wrap long lines, text does not wrap: each line stays on one line, so press Enter where you want a new line. Anything that extends past the box is cut off at its edge, so make the box larger, tick Shrink to fit the box, or make the text smaller if letters disappear. The font is built in and does not depend on the fonts installed on your computer, so labels look the same on every machine.
Dynamic text: date and serial number#
Two special words are replaced when the label is drawn, in text, barcodes, and QR codes:
| Write this | Printed as |
|---|---|
${date} | Today's date, like 2026-11-07. |
${date:%d/%m/%Y} | Today's date in a format you choose, like 07/11/2026. The codes are the usual %Y year, %m month, %d day, %H hour, %M minute. A format that is not valid is left as written. |
${serial} | The serial number from Label setup → Serial variable (1 to start). In a batch, it counts up by one for each row. |
${serial:4} | The serial number padded with zeros to 4 digits, like 0007. The width can be 1 to 12. |
For example, a barcode with the value INV-${serial} encodes INV-1. The hint above the text box reminds you: ${date} and ${serial} are dynamic. Words in a batch, such as ${Name}, are covered in Batch printing.
Address book#
The address book tool in the palette (the card with a person) lists the addresses you saved. Click one to add it to the label as a text block; the trash button beside it removes it. To add one, select a text object and press Save to address book; it is named after its first line, and saving the same name again replaces it. The book holds up to 500 addresses and is stored in addresses.json (see Where your data lives).
Barcodes#
Click the barcode tool, type the value in Enter your real product code or reference, and choose the type from the dropdown. Hovering a type explains it.
- Show value below bars prints the readable text under the bars.
- Make the object wide enough: if the bars would be too thin to print at the selected resolution, you see Barcode is too narrow. Widen the object or use a shorter value.
- Values longer than 2,048 characters are refused.
- Text size sets the size of the readable text under the bars, in points; Auto picks one that fits. Text above the bars moves it to the top.
- For EAN-13, EAN-8, and UPC-A, enter the digits without the last one and ThermalPrint calculates the check digit; a hint shows the complete number that will print.
The supported types, what each accepts, and when to use them are in the Barcode reference, including GS1-128 and GS1 Data Matrix for logistics labels.
QR codes#
The QR tool adds a square QR code. Type the content in QR content; it can be a web address, plain text, or several lines. QR error correction level chooses how much damage the code survives: Low, Medium, Quartile, or High. More correction makes a denser code, so keep the default unless the label will be scuffed. Keep the object square and at least about 20 mm wide for reliable scanning. If the object is too small for the amount of data, you see QR code is too small; enlarge the object. To put your logo in the middle of the code, see A logo in the middle.
A logo in the middle#
Many QR codes carry a small logo in the center. Select a QR code and use Logo in the center in the properties panel:
| Control | What it does |
|---|---|
| Add logo… / Change logo… | Choose a PNG, JPEG, WebP, or BMP picture. Large pictures are shrunk to at most 256 pixels on the longest side before they are stored in the design, so your .thermalprint file stays small. |
| Choose a saved logo | Pick one of your own logos from Symbols and logos (see The Label Designer). It appears when you have saved at least one. |
| Remove logo | Takes the logo off. The code goes back to normal; the error correction stays on High until you change it. |
| Logo size | The share of the code's width that is cleared for the logo, from 10 % up to the limit. The picture sits inside this clear box with a white border of one module, so the dark picture never touches the code's squares. |
| Black and white style, Cut-off, Invert black and white | The same choices as for an image (see Images and logos). A new logo starts as Black and white, which prints sharpest on a thermal printer. |
How the size is kept safe
A logo hides some of the code's squares. A QR code carries extra data so that it can still be read when some squares are lost, and ThermalPrint makes sure a code with a logo stays readable:
- The highest error correction is used. While a logo is on, the level is set to High (30 %) and the level box is greyed out.
- The code is never too small. With a logo, the code has at least 37 × 37 squares (version 5), even for very short content such as a few letters. That also keeps the logo clear of the three large corner squares and the timing lines a scanner uses to find and measure the code.
- The logo box has a size limit. It can be at most 30 % of the code's width, which is about 9 % of its area. The limit is checked in the app's own tests by reading rendered codes with a QR decoder, using the hardest logos (solid black, noise, a checkerboard), different amounts of content, and different print sizes. The codes still read when the logo is made 8 points larger than the limit, so the limit leaves a margin for blurred printing and ordinary phone cameras. Asking for more than the limit always gives the limit.
- The code must be printed large enough. A code with a logo needs squares of at least about 0.4 mm. When your QR object is narrower than that, a red note under the size slider tells you how wide to make it. If the object is so small that a square would be under three printed dots, the label is not drawn and you see QR code is too small for a logo; enlarge the object or remove the logo, instead of printing a code that might not scan.
Even with these safeguards, scan one printed label with your phone before you print a whole roll. Printers, label stock, and cameras differ.
Building the content#
Open Build the content under the QR content box to fill it in from a form instead of typing the special syntax yourself. Choose the kind, fill in the fields, and press Use this content; a field that cannot work is reported in red.
| Kind | Fields | Stored as |
|---|---|---|
| Website | Web address. https:// is added when missing; only http and https are accepted. | The address. |
| Wi-Fi | Network name, password, WPA / WEP / no password, hidden network. | A WIFI: sign-in code that phones offer to join. |
| Contact card | Name, organization, phone, email, website, address. | A vCard that phones offer to save. |
| Address, subject, message. | A mailto: link. | |
| Phone number | The number. | A tel: link. |
Shapes#
| Shape | Use |
|---|---|
| Rectangle, ellipse | Boxes, frames, and highlights. Tick Filled for a solid black shape. |
| Line | A straight line across its box. |
| Horizontal and vertical dividers | Thin rules that separate sections of a label. |
The stroke width is set in millimeters (0.05 to 20 mm). Thermal printers print only black, so use a stroke of at least 0.3 mm for lines to print crisply.
Images and logos#
The picture tool lets you choose a PNG, JPEG, TIFF, BMP, or WebP file (up to 9 MB). The image is embedded in the design, so you can move the design to another computer without the original file. Resize the object to fit; the image keeps its proportions inside the box. Color images print in black and white on a thermal printer, so a high-contrast logo looks best.
| Setting | Meaning |
|---|---|
| Original / Black and white / Dithered | Original leaves the conversion to the printer driver. Black and white makes every pixel black or white around the Cut-off. Dithered uses error diffusion, which keeps shading in photos. |
| Contrast | From −100 % to 100 %. Applied before the conversion. |
| Cut-off | Only for Black and white: pixels darker than this print black. |
| Invert black and white | Swaps black and white. Transparent areas stay transparent. |
| Reset image adjustments | Returns all of the above to their defaults. |
Symbols and logos#
The warning-triangle tool in the palette (Symbols and logos) adds ready-made shipping symbols as images: Fragile, This side up, Keep dry, Recycling, and Hazard. They are drawn in black and print crisply at any size. Under Your logos are images you kept: select an image and press Save as logo, and it joins the list for every future label (they are stored as PNG files in a logos folder, up to 60). The trash button beside a logo removes it.
Layout tips#
- Leave at least 2 mm between objects and the label edge; many printers cannot print right to the edge.
- Use Show grid, Snap to grid, and Smart guides to line things up quickly, and the arrow keys for fine adjustments.
- Lock the parts of a design that must not move, such as a logo.
- Use Focus (hide the panels) to see the label larger while you arrange it.
- Select several objects with Shift+click and press Ctrl+C and Ctrl+V to copy a whole group.