Block

Barcode

A scannable Code 39 stripe barcode for a reference or order number, with the value printed underneath.

What it is for

A barcode is the familiar row of bars, drawn as sharp vector so it stays crisp at any size. Use it when a person with a hand scanner (a warehouse, a parcel desk, an archive) needs to read a short reference such as an order or invoice number off the paper. Its value can come from your data, so every generated document carries its own number.

Only one format is available: Code 39. It is not a setting, so there is nothing to choose. It is a simple, widely read format for capital letters, digits and a few symbols. It is not a retail barcode — there is no EAN, UPC or Code 128 here, so it will not work for shop-shelf products.

Choose something else when:

a phone should open a link or read longer text — use a QR code;
people only need to read the number — use a Text block.

Add and edit it

In the palette, open Code and pick Barcode (Code 39). ("Code" on its own adds a QR code; the list beside it offers "QR code" and "Barcode (Code 39)".) The same entry is in every "Add block" menu, and typing "barcode" into the palette search finds it.
Select the barcode and use the side panel; Value is its first field.
Edit value… in the block's menu (⋮), or on right-click, selects the block and brings Value into view. Double-clicking the barcode on the page does not open anything.
To take the value from your data, click in Value, then click a field in the Data bindings pane (see the Fields and bindings article).

The bars stretch across the full width of the space the block sits in, and Height sets how tall the whole thing is. To make it narrower, put it inside a Row column.

Settings

Setting	What it does	Default and limits
Value	What the bars spell out. Fixed text, a data field, or a mix.	A sample word. Empty (or a field with no value) shows a "Barcode (no value)" marker.
Height	How tall the barcode is on the page, in millimetres. When Show text is on, the readable line takes a strip from the bottom of this height.	18 mm. At least 6 mm.
Show text	Prints the value in readable characters under the bars. Leave it on wherever someone may need to read or retype the number.	On.
Quiet zone (bar widths)	The blank margin kept at each end, counted in bar widths. It is taken out of the same total width, so a wider margin makes every bar thinner.	10. 0 or more.
Bar color	The colour of the bars.	Black.
Background	The colour behind the bars. Clearing it falls back to white — a barcode always prints on a solid field.	White.

Under these settings, Format and print shows the format, what it accepts, the exact value the bars encode ("Encodes"), how many bar widths wide it is, and how narrow the thinnest bar comes out in millimetres and printer dots, worked out from the page as it is laid out now. For a value from your data it says "with the data the canvas shows".

Which characters work

Code 39 can spell 43 characters: capital letters A–Z, digits 0–9, the space, and - . $ / + %.

Lower-case letters are printed as capitals — a scanner reads "INV-42" whether you typed "inv-42" or "INV-42". If the letter case of a reference matters, Code 39 cannot carry it.
Any other character (#, é, @, …) becomes a space. The side panel raises an issue naming each character that could not be spelled, and "Format and print" shows the value the bars really encode.
The readable line under the bars always shows exactly what the bars spell, so a substitution is visible on the page too.

Long values and thin bars

There is no length limit, but every character adds 16 bar widths, so a longer value means thinner bars in the same width. The bars are stretched across the full width the block has, so the thinnest bar is that width divided by the number of bar widths (the value plus two start/stop characters, plus the quiet zone at each end).

A printer puts ink on a grid of dots. When the thinnest bar is narrower than one dot of a 300-dpi printer (0.085 mm), such a printer cannot draw every bar, and the side panel raises an issue saying so — give the block more width or shorten the value. That is the smallest a printer can physically draw, not the smallest a scanner can read: scanners need more, and how much depends on the scanner.

Quiet zones and contrast

Keep the quiet zone at 10 or more; scanners need the blank margin. Keep Bar color strongly darker than Background, or scanners will not read the code.

Examples

Each example is a complete template stored with this documentation and checked automatically.

An invoice number with readable text

The example is barcode-1: a barcode across the page, 18 mm high, Show text on, quiet zone 10. Value is {{ $data.invoice.id }}.

Sample data:

{ "invoice": { "id": "inv-1044" } }

Expected page: bars spelling INV-1044 with "INV-1044" printed underneath. Note the capitals: the data said "inv-1044", but Code 39 only has capitals, and the readable line shows what the bars really carry. "Format and print" shows Encodes "INV-1044" (with the data the canvas shows).

A narrower barcode beside an address

The example is barcode-2: a Row with an address in the left column and the barcode in the right column, so the bars take only that column's width instead of the whole page. Value is {{ $data.order.ref }} with sample data { "order": { "ref": "PO-7731" } }. Check "Narrowest bar" in Format and print: a narrower column means thinner bars.

Output differences

PDF and HTML: sharp vector bars, in your bar and background colours.
Word (DOCX): a black-and-white picture of the same bars — custom colours are not carried over — with the readable line as a separate line of text below the picture.

Before you rely on it

Print a page at 100% scale — "fit to page" shrinks the code.
Scan it with the scanner your readers will use.
Check that it reads back exactly what "Encodes" shows.

Nothing in the editor can confirm a code scans — only a printed test can.

Troubleshooting

"Barcode (no value)" shows instead of bars. Value is empty, or its data field has no value. Type a value or choose a field that exists in your sample data.
The text under the bars is different from what I typed. Code 39 prints lower-case letters as capitals and turns characters it cannot spell into spaces. The line shows what the bars carry. Use only the 43 characters listed above.
It will not scan. Print at 100%; keep Bar color far darker than Background; keep the quiet zone at 10 or more; give the block more width or shorten the value if "Narrowest bar" is tiny.
The bars are too thin for the printer. An issue says the thinnest bar is under one printer dot. Widen the block (it fills its space; a Row column limits it), shorten the value, or lower the quiet zone.
A shop scanner says it is not a valid product code. It is Code 39, not EAN or UPC; retail barcodes are not available here.