Widgets Overview
Widgets are form elements that are not list columns: informational elements, controls, and subgrids.
What is a widget
A field is a SharePoint list column: the user enters a value and it is saved to the item. A widget is a form element that does not represent any column: it displays information, controls the form, or shows data from another location.
- Most widgets are virtual: they are not saved to the item and are excluded from the submitted payload on save. These include banner, image, related items, related documents, custom button, stepper, spacer, text block, version history, and KPI.
- The exception is Repeating Table. It is a mode of a multi-line text field and is saved into the column as JSON.
- You add a widget from the Widgets tab in the left designer palette (next to the Fields tab): drag it into a section, or click “+” to append it to the end of the section. Click a widget on the canvas to open its settings.
- All widgets share the Custom label, Width in section (1 to 12 grid columns), and Visible options. You can change visibility with a rule.
- In Display mode, all fields and widgets are read-only and the form is never marked as dirty.
List of widgets
| Widget | Code | Purpose | Saved to item |
|---|---|---|---|
| Banner | banner | Informational banner (info, warning, error, success) with a title and text that can be changed by rules. | no |
| Image | image | Static image in the form, such as a logo or diagram. The URL can include field placeholders. | no |
| Related Items | relatedItems | Subgrid of related items from another list, linked via a foreign key. | no |
| Related Documents | relatedDocuments | Documents from a library related to the item, mapped by folder or metadata. Supports upload and preview. | no |
| Repeating Table | repeatingTable | Table with repeating rows stored in a single item column, with typed columns and summaries. | yes (JSON) |
| Custom Button | customButton | Places a custom button at a chosen spot in the layout. | no |
| Process Stepper | stepper | Process stepper displaying workflow steps and the item's current status. | no |
| Spacer | spacer | Empty element for vertical spacing in the layout. | no |
| Text Block | textBlock | Text block for headings, paragraphs, and dividers, supporting field values in text. | no |
| Version History | versionHistory | Item version history and comments directly inside the form. | no |
| KPI | kpi | Value indicator (progress bar or tile) with color thresholds based on the value. | no |
Placeholders in widget text
Text in some widgets (text block, image URL, KPI subtitle, stepper title, and banner text set by a rule) can substitute field values:
| Syntax | Substituted value |
|---|---|
[Field], {Field} | value of the field with the given internal name |
@Me | name of the signed-in user |
@Today | today's date (YYYY-MM-DD) |
Data from other locations
Related items and related documents read data from other lists and libraries. For large lists (over 5,000 items), they require an indexed foreign key column; see Unindexed foreign key column.