^BY - Bar Code Field Default

Sets the module width, wide-to-narrow ratio and height that every later bar code inherits.

^BY draws nothing. It sets the three sizing defaults that every later bar code field inherits:

the width of the narrowest element;
the ratio between a wide element and a narrow one;
the bar height.

Most symbology commands take only a height of their own, so ^BY is where a linear symbol's width comes from. The payload and the module width together decide how much of the label the symbol covers.

Syntax

^BYw,r,h

Support

Supportedparsed: full · state: full · rendered: full

Every documented parameter renders the same output Labelary produces.

Labelary renders this command.

Parameters

wModule widthoptional · dots

Width of the narrowest bar and space. Every linear symbology scales from this width, the main control over symbol width.

Default: 2
Accepted range: 1 to 100 dots
Invalid value: not possible — any value is accepted. Labelary reports no warning for a width outside 1-100 and uses it as written (measured 2026-07-12), so the renderer does not validate it either.
Test coverage: Bounds pinned: below the minimum (0). No test at the minimum or maximum.

rWide-to-narrow ratiooptional · decimal

Ratio of a wide element to a narrow one, in steps of 0.1. Only two-width symbologies read it: Code 39, Codabar and the 2 of 5 family.

Default: 3
Accepted range: 2 to 3
Invalid value: discarded, and the default applies. A ratio outside 2.0-3.0 resets to 3, not to the violated bound (measured against Labelary 2026-07-12).
Test coverage: Bounds pinned: maximum (3.0). No test at the minimum or one step outside the range. The invalid-value rule is pinned by 3 tests.

hBar code heightoptional · dots

Default height for bar codes that do not carry their own height argument.

Default: 10
Accepted range: 1 to 32000 dots
Invalid value: clamped to the nearest allowed value. We measured this against live Labelary on 2026-07-12. The renderer clamps an out-of-range value to the violated bound, and does not ignore it.
Test coverage: Bounds pinned: below the minimum (0). No test at the minimum or maximum. The invalid-value rule is not pinned by a test.

Behavior

^BY is not a field command. It takes effect where it appears and stays in effect until the next ^BY, so one near the top of a format sizes every symbol below it. A symbology's own height argument wins over h. Leave that argument empty and the ^BY height applies.

The ratio reaches only the symbologies that have two element widths — Code 39, LOGMARS, Codabar, MSI, Plessey and the 2 of 5 family. The fixed-ratio symbologies ignore it: the whole UPC and EAN family, Code 93, Code 49, PDF417 and the two-dimensional codes.

The printed ratio is not always the requested ratio, because bars print in whole dots. The guide's own worked example: at a module width of 9 dots a ratio of 2.4 wants a wide bar of 21.6 dots. That rounds to 22 and prints as 2.44:1. At a module width of 1 dot every ratio below 3.0 collapses to 2:1, because nothing lies between two dots and three. Widen the module before the ratio.

Two-dimensional symbologies read ^BY selectively. ^BX Data Matrix and ^B7 PDF417 take the height and ignore the module width and the ratio. ^BQ QR Code and ^BD MaxiCode ignore ^BY altogether and take their size from their own magnification argument.

A larger module width also enlarges the interpretation line. We measured this against Labelary on 2026-07-30: the human-readable text scales with the module width and not with the current font. A symbol widened to fill a label therefore grows its text too.

Tested behavior

Differences from the specification

Labelary against the ZPL II guide

Where Labelary — our compatibility target — behaves differently from the printed specification.

The guide gives the module width as 1 to 10 dots. Labelary documents 1 to 100 and uses it as written (measured 2026-07-12); the renderer follows Labelary. — pinned by test_by_module_width_above_ten_is_not_clamped, test_by_module_width_out_of_range_is_silent

Example

The same Code 39 payload at two module widths. Neither ^B3 gives a height, so both take it from the preceding ^BY:

^XA
^BY2,2,60
^FO50,50^B3N,N,,Y,N^FDNARROW^FS
^BY4,3,60
^FO50,200^B3N,N,,Y,N^FDNARROW^FS
^XZ

Open in viewer

^B3 Code 39 Bar CodeThe general-purpose alphanumeric symbology, readable by every scanner and the safest default for internal labeling.
^BC Code 128 Bar CodeThe most common symbology for shipping and GS1 application identifiers, with four data-encoding modes.
^BI Industrial 2 of 5 Bar CodeNumeric symbology that encodes data in the bars only. The spaces are separators only.
^BJ Standard 2 of 5 Bar CodeNumeric symbology with wide spaces between characters, the least dense of the 2 of 5 family.
^FD Field DataSupplies the text or barcode content of the field.

^BY - Bar Code Field Default

On this page