Schema

Bands

Learn about report bands -- header, detail, and footer -- and how they control report layout.

What are bands?

Bands are horizontal sections that make up a report. They define the vertical structure: what appears at the top, what repeats for each data row, and what appears at the bottom.

Each band has a type, a fixed height (in mm), and an array of components positioned within it.

Band types

The header band renders once at the top of the report. Use it for titles, logos, dates, and company information.

{
  type: 'header',
  height: 80,
  components: [
    {
      type: 'text',
      position: { x: 0, y: 10, width: 300, height: 30 },
      content: 'Monthly Sales Report',
      fontSize: 24,
      fontWeight: 'bold',
    },
    {
      type: 'text',
      position: { x: 0, y: 45, width: 200, height: 20 },
      content: '{{formatDate(reportDate, "MMMM yyyy")}}',
      fontSize: 12,
      color: '#64748b',
    },
  ],
}

Detail

The detail band repeats for each item in a bound data array. It requires a dataBinding property that references an array in the data context.

{
  type: 'detail',
  height: 28,
  dataBinding: 'items',
  components: [
    {
      type: 'text',
      position: { x: 0, y: 4, width: 200, height: 20 },
      content: '{{item.name}}',
      fontSize: 12,
    },
    {
      type: 'text',
      position: { x: 400, y: 4, width: 100, height: 20 },
      content: '{{formatCurrency(item.price, "USD")}}',
      fontSize: 12,
      textAlign: 'right',
    },
  ],
}

The footer band renders once at the bottom, after all detail bands. Use it for totals, notes, and signatures.

{
  type: 'footer',
  height: 50,
  components: [
    {
      type: 'text',
      position: { x: 400, y: 10, width: 100, height: 20 },
      content: '{{formatCurrency(sum(items, "price"), "USD")}}',
      fontSize: 14,
      fontWeight: 'bold',
      textAlign: 'right',
    },
  ],
}

Height

Every band must declare its height in millimeters. This controls the vertical space allocated for the band’s components.

height: 60  // 60mm tall band

The engine uses band heights to calculate page breaks and total report length.

Data binding

Detail bands require a dataBinding property pointing to an array in the data:

dataBinding: 'items'

Automatic iterator naming

The engine automatically derives the iterator variable name by removing the trailing “s” from the array name:

dataBindingIterator variable
itemsitem
productsproduct
employeesemployee
entriesentrie

Custom iterator name

When the automatic naming does not produce the right result, use the iteratorName property:

{
  type: 'detail',
  height: 28,
  dataBinding: 'entries',
  iteratorName: 'entry',
  components: [
    {
      type: 'text',
      position: { x: 0, y: 4, width: 200, height: 20 },
      content: '{{entry.label}}',
      fontSize: 12,
    },
  ],
}

Band ordering

Bands are rendered in the order they appear in the bands array. A typical report follows this pattern:

  1. Header — once at top
  2. Detail — repeated per data row
  3. Footer — once at bottom

You can include multiple header or footer bands if your layout requires them.

Planned band types

The following band types are planned for future releases:

  • page-header — repeats at the top of every page (after the first)
  • page-footer — repeats at the bottom of every page
  • group-header — renders before each group when data is grouped
  • group-footer — renders after each group with group aggregates

Next steps