Card

Overview

A Card (card) is a self-contained block that displays a set of labelled fields as a structured table. Unlike a section (which lays out child nodes vertically), a card owns its field definitions directly through a fields array, making it more portable and easier to compose inside layout groups.

Four variants give the card different visual treatments:

Title & Header

Data Binding

All field value expressions resolve against the full JSON payload root - dataPath does not restrict which payload fields can be referenced. Setting dataPath tells the Designer which object in your payload to use when suggesting field names, but you can reference any payload path in a value string regardless.

Variant

Field Layout

Border & Background

Spacing

marginTop, marginBottom and width are not read by the card renderer - the renderer's card case has no code path that consumes them. To control spacing around a card, wrap it in a layout_group or section, whose own marginTop/marginBottom props are consumed. To size a card inside a layout_group, use that group's columns[].width, not a width prop on the card itself.

Variant Details

Default

The standard label-value block. Each field renders as a two-column row (label left, value right) or a single stacked column when labelPosition: "top". Rows are separated by innerBorderStyle lines.

{
  "type": "card",
  "props": {
    "title": "Customer",
    "variant": "default",
    "showHeader": true,
    "labelPosition": "left",
    "labelWidth": 110,
    "valueAlign": "left",
    "borderStyle": "full",
    "innerBorderStyle": "minimal",
    "fields": [
      { "key": "name",    "label": "Name",    "value": "{{customer.name}}" },
      { "key": "email",   "label": "Email",   "value": "{{customer.email}}" },
      { "key": "phone",   "label": "Phone",   "value": "{{customer.phone}}" }
    ]
  }
}

Summary

Each field becomes a mini tile - a small table cell with the label displayed in a filled header bar (accentColor background, contrast text) and the value centered below. Tiles are arranged in rows of up to columns tiles each (1, 2 or 3; columns: 0 falls back to 1, it does not auto-fill).

Use emphasizeLastRow: true and showDivider: true to visually separate a total row from sub-totals.

{
  "type": "card",
  "props": {
    "title": "Order Totals",
    "titleIcon": "star",
    "variant": "summary",
    "showHeader": false,
    "columns": 1,
    "valueAlign": "right",
    "emphasizeLastRow": true,
    "showDivider": true,
    "fields": [
      { "key": "subtotal", "label": "Subtotal",  "value": "{{subtotal}}",  "format": "currency" },
      { "key": "tax",      "label": "GST (10%)", "value": "{{tax}}",       "format": "currency" },
      { "key": "total",    "label": "Total",     "value": "{{total}}",     "format": "currency" }
    ]
  }
}

Address

Values are rendered as a single multiline text block - one line per field, labels omitted. Ideal for postal addresses, delivery notes, or any block where the formatting itself conveys structure.

The outer borderStyle defaults to "minimal" for this variant (bottom-line only). Set borderStyle: "none" for a borderless address block.

{
  "type": "card",
  "props": {
    "title": "Deliver To",
    "variant": "address",
    "showHeader": false,
    "borderStyle": "none",
    "fields": [
      { "key": "line_0", "label": "Name",           "value": "{{deliveryName}}" },
      { "key": "line_1", "label": "Street",         "value": "{{deliveryStreet}}" },
      { "key": "line_2", "label": "City/State/Zip", "value": "{{deliveryCity}}, {{deliveryState}} {{deliveryPostcode}}" }
    ]
  }
}

Grouped

Renders a nested payload object as a stack of sub-cards. Instead of a flat fields array, a grouped card holds a children array - each child is typically a default or address card. Use this variant when your payload contains nested objects (for example, a shipTo object that itself contains a contact sub-object) and you want each level to appear as a distinct, titled card block.

Fields

The fields array defines the rendered rows (or tiles, for summary). Fields are rendered in declaration order.

Field Properties

Field Formats

Formats can also be embedded inline in the value string using the pipe syntax: "{{amount|currency}}".

Visibility

To hide an entire card, set visible: false in its props. This is a generic check applied before any node is built, and it works on every node type including card.

A top-level hidden prop on the card itself is not read. hidden only has an effect inside individual fields[] entries (see Field Properties), where it omits that one field from the rendered output.

Hiding a field when its value is empty

hidden is decided once, in the template. To decide per document instead, set hideWhenEmpty: true on the field. When every {{token}} in the field's value resolves to a missing path, null, or text that is empty or only spaces, the whole field is left out, label included, rather than showing a label with nothing beside it. This applies in the default, address and summary variants.

• 0 and false are values, not empty ones, so a field whose token resolves to either still shows.
• A value that is literal text with no token is never hidden.
• If value holds more than one token, the field is hidden only when all of them are empty. "{{city}}, {{state}}" still shows when either city or state has a value, and is left out when both are empty.

{
  "type": "card",
  "props": {
    "title": "Customer",
    "fields": [
      { "key": "name",  "label": "Name",        "value": "{{customer.name}}" },
      { "key": "vat",   "label": "VAT Number",  "value": "{{customer.vatNumber}}",  "hideWhenEmpty": true },
      { "key": "terms", "label": "Credit Days", "value": "{{customer.creditDays}}", "hideWhenEmpty": true }
    ]
  }
}

With "vatNumber": "" and "creditDays": 0 in the payload, the card shows Name and Credit Days (as 0) and leaves out VAT Number.

Examples

Info card -- two columns, top label

{
  "type": "card",
  "props": {
    "title": "Order Details",
    "titleIcon": "package",
    "variant": "default",
    "showHeader": true,
    "labelPosition": "top",
    "columns": 2,
    "fieldGap": 4,
    "borderStyle": "full",
    "innerBorderStyle": "none",
    "padding": 10,
    "fields": [
      { "key": "orderId",    "label": "Order Number", "value": "{{orderId}}" },
      { "key": "orderDate",  "label": "Date",         "value": "{{orderDate}}",  "format": "date" },
      { "key": "reference",  "label": "Reference",    "value": "{{reference}}" },
      { "key": "dueDate",    "label": "Due Date",     "value": "{{dueDate}}",    "format": "date" }
    ]
  }
}

Summary card -- totals block on the right

Pair this card with a table on the left inside a layout_group:

{
  "type": "card",
  "props": {
    "title": "Invoice Totals",
    "variant": "summary",
    "showHeader": false,
    "accentColor": "theme.primary",
    "columns": 1,
    "valueAlign": "right",
    "labelBold": true,
    "emphasizeLastRow": true,
    "showDivider": true,
    "borderStyle": "full",
    "innerBorderStyle": "full",
    "padding": 10,
    "fields": [
      { "key": "subtotal", "label": "Subtotal",   "value": "{{subtotal}}",   "format": "currency" },
      { "key": "discount", "label": "Discount",   "value": "{{discount}}",   "format": "currency" },
      { "key": "tax",      "label": "GST (10%)",  "value": "{{tax}}",        "format": "currency" },
      { "key": "total",    "label": "Total Due",  "value": "{{totalDue}}",   "format": "currency" }
    ]
  }
}

Address card -- borderless

{
  "type": "card",
  "props": {
    "title": "Ship To",
    "variant": "address",
    "showHeader": false,
    "borderStyle": "none",
    "accentColor": "theme.primary",
    "padding": 0,
    "fields": [
      { "key": "company", "label": "Company", "value": "{{shipTo.company}}" },
      { "key": "street",  "label": "Street",  "value": "{{shipTo.street}}" },
      { "key": "suburb",  "label": "City",    "value": "{{shipTo.city}}, {{shipTo.state}}  {{shipTo.postcode}}" },
      { "key": "country", "label": "Country", "value": "{{shipTo.country}}" }
    ]
  }
}

Placing Cards in Layout Groups

Cards placed inside a layout_group fill the column width computed by the group. Pin a card to a fixed pt size by setting width on the group's columns[] entry, not on the card itself - a width prop on the card is not read:

{
  "type": "layout_group",
  "props": { "columns": [{ "width": "star" }, { "width": 160 }], "columnGap": 12 },
  "children": [
    { "type": "table", "props": { "...": "..." } },
    {
      "type": "card",
      "props": {
        "variant": "summary"
      }
    }
  ]
}

Related Pages

• Section - child-node-based layout block; use cards when you want self-contained field ownership
• Layout Group - multi-column container for placing cards side-by-side
• Table - for array-backed tabular data
• Template Settings - theme tokens referenced by accentColor, borderColor, and headerFillColor