Display Controls Overview
Display controls show information — they do not collect user input. Use them to add context, instructions, images, rich HTML content, and file upload widgets to your forms. Unlike input controls, display controls do not write values back to the form data model.
The Display Control Types
label
Plain text paragraph. Uses the description field as content. Ideal for instructions and help text.
header
Section heading. Supports h1–h6 levels and optional divider line. Use to visually separate form sections.
image
Inline image. Set src, alt, and responsive width. Supports external URLs and base64.
html
Rich HTML content. Rendered through a 6-layer XSS sanitisation pipeline. Supports links, bold, lists, code blocks.
file-upload
File attachment widget. Supports single and multiple files, file type filtering, size limits, and upload progress display.
Display Controls vs Input Controls
| Characteristic | Display Controls | Input Controls |
|---|---|---|
| User interaction | Read-only (file-upload is interactive) | Interactive, accept user input |
| Writes to data model | No (file-upload fires a callback) | Yes, via binding |
| Validation | Not applicable | Full validation support |
| Visible in view mode | Configurable per control | Configurable per control |
| Design palette group | "display" | "input" |
Common Properties
Display controls share a subset of the common control properties. Note that required, validation, and binding are not applicable to most display controls:
| Property | Applies to | Description |
|---|---|---|
id | All | Unique control identifier |
type | All | Control type string |
label | file-upload | Label shown above (most display controls use description instead) |
description | label, html | The text/HTML content to display |
order | All | Position within section |
width | All | Column span: full / half / third |
hidden | All | Hide the control in all modes |
modeVisibilitySettings | All | Show/hide per operating mode |
visibilityRule | All | Expression-based conditional visibility |
Placement in Form Schema
Display controls are placed in the same controls[] array as input controls. They appear in the section at the position defined by order:
{
"controls": [
{
"id": "section-intro",
"type": "html",
"order": 1,
"width": "full",
"description": "<p>Please complete all fields in this section. Fields marked with * are required.</p>"
},
{
"id": "first-name",
"type": "text",
"label": "First Name",
"order": 2,
"required": true,
"width": "half"
}
]
}XSS Security Note
The html control passes all content through a 6-layer sanitisation pipeline before rendering. Never bypass this pipeline. See HTML Control Security for the full security model.