Skip to content

Label Layouts

Introduction

Layouts control what will be printed on each label and how it is arranged.

Things to know:

  • Layouts can be static (each label is exactly the same) or dynamic (data is inserted into the label from the data list). Most commonly, layouts are a mix of both.
  • Layouts are responsive, meaning they will resize to fit the template dimensions. Usually, they'll be designed to fit specific labels.
  • Layouts are made up of one or more layout elements.

The entire label layout specification can be viewed here

Examples

Here is an example of a layout with a barcode in the top 75%, and text in the bottom 20%. Both the barcode and the text show a package label:

{
  "labelContentLayoutElements": [
    {
      "elementType": "CODE128_BARCODE",
      "valueTemplate": "{{package.label}}",
      "yStartFraction": 0.25
    },
    {
      "elementType": "TEXT",
      "valueTemplate": "{{package.label}}",
      "yEndFraction": 0.2
    }
  ]
}

Here is how this layout renders on a 3x1 thermal label:

Barcode/text layout rendered on 3x1 thermal label

Barcode/text layout rendered on 3x1 thermal label

Here is how this layout renders on an Avery 8160 label sheet:

Barcode/text layout rendered on Avery 8160

Barcode/text layout rendered on Avery 8160

Layout Elements

A layout element is a single element that appears somewhere on a label. Text, images, and barcodes are all examples of layout elements.

Each layout element has a specific elementType that describes how it will appear. Available element types:

elementType Description
TEXT A paragraph of text
TABLE A table made of rows/columns of cells, defined with HTML
IMAGE An image file (passed as base64)
CODE128_BARCODE A Code 128 barcode
CODE39_BARCODE A Code 39 barcode
QR_CODE A QR code
BOX A rectangular box used for borders or background fills

Text

A TEXT layout element adds a paragraph of text.

Tables

A TABLE element adds multiple pieces of text formatted in rows and columns.

  • All text in a table has a consistent font size and spacing.
  • Table borders are not displayed by default.
  • Tables are defined with HTML.

Images

An IMAGE layout element adds an image file onto the label.

  • Images are centered in the layout element and fit to the available space.
  • Image data is passed as base64 and accessed via filename (see value templates).

Barcodes

The CODE128_BARCODE and CODE39_BARCODE elements display a scannable 1D barcode that encodes a piece of text.

  • The barcode will fill the layout element area horizontally and vertically.
  • The barcode encodes whatever is produced by the value template.
  • Use CODE128_BARCODE for Metrc tags and most general-purpose use. CODE39_BARCODE is available for systems that specifically require Code 39.

QR Codes

A QR_CODE element displays a scannable QR code that encodes a piece of text.

  • QR codes are centered in the layout element and fit to the available space, with padding.
  • The QR code encodes whatever is produced by the value template.

Boxes

A BOX element draws a rectangular box inside the layout element area. It does not use a value template.

  • boxStrokeColor sets the border color (hex, default #000000).
  • boxStrokeWidth sets the border width in points (default 0.5).
  • boxStrokeAlpha sets the border opacity (0.0–1.0, default 1.0).
  • boxBackgroundColor sets the fill color (hex). Omit to disable fill.
  • boxBackgroundAlpha sets the fill opacity (0.0–1.0, default 1.0).

Position and Sizing

Layout elements are positioned as rectangles inside the printable area. The boundaries of the rectangle are specified as fractions of the label's printable width and height. This allows the same layout to be reused across labels of different sizes.

Layout elements use the following values to define size and position:

  • xStartFraction - left edge (default 0)
  • xEndFraction - right edge (default 1)
  • yStartFraction - bottom edge (default 0)
  • yEndFraction - top edge (default 1)

Values are decimals between 0 and 1 (for example, 0.05 = 5% of the total dimension).

Note: The default start and end values fill the entire printable area. In the earlier example, only one fraction is defined for each layout element — the rest fall back to defaults.

Aspect Ratio Limits

By default, layouts will fill the available template width and height. You can define a minimum and maximum aspect ratio for the layout, which will limit how much it will stretch.

Layouts use two values to control this:

  • minAspectRatio
  • maxAspectRatio

Note: If T3 detects a minimum or maximum aspect ratio is reached, it will center the layout inside the template.

Textual Elements

Textual elements (TEXT, TABLE) have options to control how the text appears: size, font, spacing, positioning, etc.

Text Formatting

Textual elements can control font size, font family, and paragraph spacing.

  • paragraphFontSize controls the font size. Default is 6.
  • paragraphSpacing controls the paragraph spacing. Default is 6. The font size cannot exceed the spacing.
  • paragraphFontName controls the font family. Supported fonts:
  • Times-Roman
  • Times-Bold
  • Times-Italic
  • Times-BoldItalic
  • Helvetica (default)
  • Helvetica-Bold
  • Helvetica-Oblique
  • Helvetica-BoldOblique
  • Courier
  • Courier-Bold
  • Courier-Oblique
  • Courier-BoldOblique
  • Symbol
  • ZapfDingbats

Text Alignment

Textual elements can control how text is aligned inside the element boundaries — or, in the case of tables, inside each cell.

  • horizontalParagraphAlignment controls horizontal alignment: LEFT, CENTER (default), RIGHT
  • verticalParagraphAlignment controls vertical alignment: TOP, CENTER (default), BOTTOM

Responsive Sizing

Textual elements also allow you to specify how the text behaves when it overflows the layout element boundaries, using paragraphTextResizeStrategy:

  • ALLOW_OVERFLOW (default) displays text at its initial font size, even if it overflows the layout element boundaries.
  • TRUNCATE_TEXT preserves the initial font size and removes letters from the end until the remaining text fits. An ellipsis (...) is appended to indicate truncation.
  • SHRINK_TEXT preserves the initial text length but progressively reduces the font size until the text fits.

Note: TRUNCATE_TEXT and SHRINK_TEXT are best-effort — they will only shorten or shrink the text to a certain point before giving up.

Element Values

A value is the data that appears inside a layout element: paragraph text, table contents, image data, or barcode contents. This data is produced by a value template.

Value Templates

The value template is a string used to specify text, HTML, or images that will appear inside the element. Different element types use the value template differently, and some do not use it at all.

Each value template is processed before being rendered onto the label.

Template Processing

All value templates are processed with Jinja before being added to the label.

  • TEXT uses the processed value as the text displayed inside the element.
  • Example: Hello, my name is {{ user.name }}
  • TABLE uses the processed value as the HTML table displayed inside the element.
  • Example: <table><tr><td><b>First Name</b></td><td><b>Last Name</b></td></tr><tr><td>{{ user.firstName }}</td><td>{{ user.lastName }}</td></tr></table>
  • IMAGE uses the processed value as a reference to a base64-encoded image.
  • CODE128_BARCODE / CODE39_BARCODE use the processed value as the barcode's scan value.
  • QR_CODE uses the processed value as the QR code's scan value.
  • BOX does not use a value template.

Jinja Templating

Value templates use Jinja syntax. The most important feature is variable interpolation with double curly braces:

{{ package.label }}

When the label PDF is generated, T3 processes each value template against the data available for that label. Variables are drawn from three namespaces:

  • Per-label data: each entry in your data list. For example, if your data list contains {"package": {"label": "1A44..."}}, then {{ package.label }} renders 1A44....
  • common.*: values shared across every label, passed via commonContentData. For example, {{ common.facilityContactInfo.phoneNumber }}.
  • images.*: base64 image data you supplied, accessed by filename. For example, {{ images['logo.png'] }}.
  • t3.*: built-in text and images provided by T3. For example, {{ t3.images['t3_logo.png'] }} or {{ t3.text.poison_control_center_phone }}.

Jinja also supports conditionals, loops, and filters, which can be useful for labels that conditionally display information:

{% if package.isOnHold %}ON HOLD{% endif %}

{{ package.item.name | upper }}

If a variable is missing from the data, T3 returns a 400 Bad Request error identifying which variable was undefined. See Handling Errors in the tutorial for an example.

Next Steps