zpl.tools
Labelary extensions

~BR - Background Rectangle

A Labelary extension, not a ZPL command: fills a rectangle in an RGB color behind the label to simulate colored stock.

~BR is not a ZPL command. Labelary added it to its own renderer, like ~BI, and it is the cheaper of the two. Instead of an encoded image it takes a rectangle and an RGB triple, and fills that area behind the label. No Zebra printer implements it, it appears in no Zebra reference, and it is absent even from Labelary's own 230-row command table. The only place that documents it is Labelary's command reference, which flags it as a Labelary extension, one of exactly two. The RGB triple is the giveaway: ZPL has no color model at all, so a command that names a color cannot be ZPL. On real hardware the BR mnemonic is ^BR, GS1 DataBar.

Syntax

~BRx,y,w,h,r,g,b

Support

Not implemented yetparsed: none · state: none · rendered: none

Recognised as valid ZPL and not implemented yet, so it has no effect on the output.

A Labelary-specific extension rather than ZPL, so no Zebra printer accepts it and it appears in no Zebra reference and in no Labelary command table. It draws a colored background, so it would change the rendered label. That makes it a real gap, not a safe command to ignore, and nothing schedules it yet. The renderer also does not recognize its own name. The dispatcher matches the two-character mnemonic without the prefix, so the parser reads it as ^BR GS1 DataBar. It reports no unknown command; see the recorded deviations. — not pinned by a test

Absent from Labelary's command table.

Parameters

xHorizontal positionoptional · dots

Left edge of the rectangle, from the left edge of the label.

Default
0
Accepted range
0 to the label width dots
Invalid value
not documented, and we have not measured it. Labelary documents the bounds but not what a position past the label edge does; the renderer does not implement the command.
Test coverage
No test at the minimum, maximum or one step outside the range.
yVertical positionoptional · dots

Top edge of the rectangle, from the top of the label.

Default
0
Accepted range
0 to the label height dots
Invalid value
not documented, and we have not measured it. Labelary documents the bounds but not what a position past the label edge does; the renderer does not implement the command.
Test coverage
No test at the minimum, maximum or one step outside the range.
wWidthoptional · dots

Width of the filled rectangle.

Default
1
Accepted range
1 to the label width dots
Invalid value
not documented, and we have not measured it. Labelary documents the bounds but not the behavior outside them; the renderer does not implement the command.
Test coverage
No test at the minimum, maximum or one step outside the range.
hHeightoptional · dots

Height of the filled rectangle.

Default
1
Accepted range
1 to the label height dots
Invalid value
not documented, and we have not measured it. Labelary documents the bounds but not the behavior outside them; the renderer does not implement the command.
Test coverage
No test at the minimum, maximum or one step outside the range.
rRed componentoptional · integer

Red channel of the fill color. ZPL itself has no color model, which is why this lives outside ZPL.

Default
0
Accepted range
0 to 255
Invalid value
not documented, and we have not measured it. Labelary documents the bounds but not the behavior outside them; the renderer does not implement the command.
Test coverage
No test at the minimum, maximum or one step outside the range.
gGreen componentoptional · integer

Green channel of the fill color.

Default
0
Accepted range
0 to 255
Invalid value
not documented, and we have not measured it. Labelary documents the bounds but not the behavior outside them; the renderer does not implement the command.
Test coverage
No test at the minimum, maximum or one step outside the range.
bBlue componentoptional · integer

Blue channel of the fill color. All seven arguments are optional; a ~BR with none of them clears every background rectangle registered so far.

Default
0
Accepted range
0 to 255
Invalid value
not documented, and we have not measured it. Labelary documents the bounds but not the behavior outside them; the renderer does not implement the command.
Test coverage
No test at the minimum, maximum or one step outside the range.

Behavior

It registers a rectangle, it is not a field

~BR is not ^GB with color. ^FO and ^FT do not position it, ^FS does not close it, it has no border, and it is always solid. It also belongs to no one label: Labelary registers the rectangle and fills it behind every label it renders from then on. Measured against api.labelary.com at 8dpmm on 2026-07-29:

  • Registration outlives ^XZ. A ~BR before the first ^XA of a two-label format tints the second label as well as the first.
  • Registrations accumulate, and a later one draws over an earlier one where they overlap.
  • ~BR with no arguments at all clears every rectangle registered so far, and the labels after it come out plain. That is the only way to remove one.
  • Either side of ^XA works. A ~BR inside the format fills the same background as a ~BR before it.

The rectangle goes behind everything the format prints, so text and bar codes over it stay black and legible. No "whole label" shorthand exists. To tint a whole label, give the rectangle the label's own dimensions in dots. A 4 by 2 inch label at 8dpmm needs 812 by 406.

What this service does

The renderer fills nothing, so the label renders on plain white. It reports the command once, as valid ZPL this renderer does not support yet, and reads nothing else out of it.

Until August 2026 the parser dispatched on the two-character mnemonic alone and did not check the prefix, so ~BR… reached the code path for ^BR GS1 DataBar. That read the coordinates and the color channels as bar code arguments. It answered six warnings about a bar code that is not there. Inside ^XA … ^XZ it also made the next field a bar code field, so ~BR50,50,300,200,252,252,121 followed by ^FO70,90^A0N,40,40^FD1234567890123^FS drew a GS1 DataBar symbol where Labelary draws a yellow rectangle. ~BR is now its own command and neither happens.

Colored stock in production

ZPL cannot do it. A thermal printer marks the media in a single color. The color argument of ^GB chooses between black ink and white erasure, not between hues. Color comes from the media: order colored or pre-printed stock and let the printer put black on top of it. Keep ~BR for previews if it helps, and strip it before the format reaches a printer.

Differences from the specification

Labelary against the ZPL II guide

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

  • The command is not in the ZPL II guide, and it is in no Labelary command table either. It is Labelary's own extension, one of exactly two, and only the engine's behavior documents it. — not pinned by a test

zpl.tools against Labelary

Where our output differs from Labelary for the same input. These are the differences that break a migration.

  • Labelary fills the rectangle behind the label; the renderer draws no background, so the label renders on plain white. — not pinned by a test
  • The parser dispatches on the two-character mnemonic without the prefix, so ~BR reaches the ^BR GS1 DataBar arm. It reads the coordinates and color channels as bar code arguments. No diagnostic reports the mismatch. The renderer instead reports six argument warnings against ~BR. We measured this on 2026-07-29 with ~BR50,50,300,200,252,252,121: they read Value 50 is greater than maximum value 12; used 1 instead and Value 300 is greater than maximum value 10; used 10 instead. — not pinned by a test
  • Because ^BR is a bar code command, a ~BR inside ^XA … ^XZ makes the next field a bar code field. We measured this on 2026-07-29: ^FD1234567890123^FS after it draws a GS1 DataBar symbol, and ^FDColored stock^FS draws nothing, so the label comes out blank. Before ^XA, where Labelary's own examples put it, the misparse costs only the warnings and the label renders normally. — not pinned by a test

Example

A pale yellow rectangle 300 by 200 dots at (50, 50), with a line of text printed over it:

~BR50,50,300,200,252,252,121
^XA
^FO70,90^A0N,40,40^FDColoured stock^FS
^XZ

Open in viewer

  • ~BI Background ImageA Labelary extension, not a ZPL command: draws a Base64-encoded image behind the label to simulate colored or pre-printed stock.
  • ^BR GS1 DataBar Bar CodeThe GS1 DataBar (formerly RSS) family, including the composite variants that stack a 2D component above a linear one.
  • ^GB Graphic BoxDraws a rectangle, a line or a filled block.
  • ^GF Graphic FieldDraws a bitmap sent inline with the label.

~BI - Background Image

A Labelary extension, not a ZPL command: draws a Base64-encoded image behind the label to simulate colored or pre-printed stock.

On this page

SyntaxSupportParametersBehaviorIt registers a rectangle, it is not a fieldWhat this service doesColored stock in productionDifferences from the specificationExampleRelated commands