Related Items

Subgrid of related items from another list, linked via a foreign key.

Widget description: relatedItems

The widget displays a table of items from another list that belong to the current item (1:N relationship), such as project tasks or order lines. The link is defined by a foreign key—a column in the target list whose value matches the key of the current item. It is a virtual widget: data remains in the target list and nothing is saved to the current item. A similar widget for files is Related Documents.

Adding to the form

1. On the Widgets tab in the left palette, select Related Items (subtitle “Widget · 1:N records”) and drag it into a section, or click “+”.
2. In the inspector, select the Target list. Site lists are offered (standard lists, not libraries).
3. Select the Foreign key column in target list.
4. Check the Displayed columns in table and rename them if needed.

Until a list and a foreign key column are selected, the widget displays “Widget is not fully configured” in the form.

Inspector settings

Displayed columns of type Person and Lookup (including multi-value) added manually in configuration or via AI are loaded using $expand and displayed as text (person name, lookup value, comma-separated for multiple values). Previously, such columns resulted in an HTTP 400 error. Audit columns (Created By, Modified By, Created, Modified, ID, Attachments) are at the bottom of the list under the “System columns” divider.

The displayed columns picker includes text, choice, number, lookup (including multi-value), person (including multi-value), date, yes/no, and counter columns; technical and hidden columns are omitted, and the column type is shown after the name. The foreign key column picker remains limited to the default set of columns. The number of loaded rows (rowLimit, 1 to 100, default 25 for a new widget) is set in the inspector under “Maximum number of records” (clamped to 1–100).

Visual column formatting

In the large widget configuration dialog (Columns tab), under Displayed columns, you can choose a Format for each column directly in its row (the arrow at the end of the row expands details; one row is expanded at a time). Settings are stored in columnFormatting keyed by the column's internal name. Without a format, or when the value does not fit the format (for example text in a progress bar), plain text is shown. You can inspect the result in the preview at the bottom of the dialog: open it with Show preview and refresh it after further edits with Refresh preview (until refreshed, a notice warns that it does not reflect the latest changes).

Columns referenced as maxField or statusField are loaded even when they are not displayed in the table.

Related items filter

On the Filter tab of the large configuration dialog, you can add extra conditions to the item link, such as showing only active items or only your own items.

• Root toggle: the item must match all conditions (AND) or at least one condition (OR).
• Condition: target list column, operator (equals, not equals, greater/less than, contains text, starts with), and value. For person and lookup columns, only equals and not equals are available (compared by ID). Available operators depend on the column type.
• Value source: fixed value (text, number, Yes/No, date, or column choice), field from this form (changing the field reloads the table; an empty field value skips the condition), Today token with day offset (e.g., -30), or Signed-in user.
• Groups: the + Add group button inserts an indented group with its own AND/OR (up to 8 levels). Empty groups are ignored.
• The Resulting OData filter is shown live below the builder; an invalid condition shows an error without blocking save, but the widget will display a filter error instead of data at runtime.

Expert mode: the Direct OData expression toggle reveals a text box for a custom OData fragment (for example Stav eq 'Done'). It is combined via AND with both the visual filter and the item link. Intended for designers only; the expression is not validated—do not insert user-entered values into it.

Key and foreign key

The widget queries the target list for items where foreign key column = source key value. The source key is either the current item's ID (@itemId, most common) or the value of another form field (for example Zakazka, in which case the item does not need to be saved first). The widget detects the foreign key column type automatically and builds the appropriate filter:

A key value from a lookup, person, or metadata field is converted to an ID (for person and lookup) or a term identifier. When the key is ID, filtering is performed directly by ID.

Unindexed foreign key column (5,000-item threshold)

SharePoint refuses to filter a list with more than 5,000 items by an unindexed column (List View Threshold). The widget prevents this:

• In the designer: after selecting the foreign key column, the widget checks whether it is indexed and how many items the list has. If the column is unindexed and the list has over 5,000 items, a warning “Column … is not indexed” and an Index column button appear. Clicking the button indexes the column in SharePoint (requires list administrator permissions) and the warning disappears on success.
• At runtime: in that situation, the query is not sent at all and the widget shows the error “Column ‘…’ is not indexed. Lists with more than 5,000 items require it to be indexed. Ask the list owner to index it.” The same message appears if SharePoint returns a threshold error.
• The ID column is always indexed, so no check is needed there. If indexing status or item count cannot be determined, the query is executed and SharePoint decides.

Runtime behavior

• New: if the source key is @itemId, the item does not have an ID yet. The widget displays “Related records will be available after the item is saved for the first time” and hides the New item button. With another source key, data loads as soon as the key field has a value.
• Edit: loads up to rowLimit rows (default 25), with the count, Refresh button, and optionally New item button in the header. Changing the source field triggers a reload.
• Display: the same table, without the New item button. The widget never marks the form as dirty.
• The New item button opens the target list's new item form in a new tab. After saving there, click Refresh records; the table does not update automatically.
• Sorting and filtering: click a column header to sort (click repeatedly to toggle direction; numeric values sort numerically). The filter searches across all displayed columns and shows “Found: x of y”. It operates only on loaded rows.
• Column widths can be resized by dragging the right edge of the header (persists until the form is closed).
• Item detail link: the linkToItemField column opens the item detail in a dialog inside the form. If you edit and save the item in the dialog, the dialog closes and the table refreshes.
• An empty value is shown as “—”; an object value (such as a lookup) is shown as JSON text.

Text translations

The title (customLabel) and column labels (columnLabels, keyed by internal column name) can be translated. Built-in widget UI text (filter, buttons, messages) switches automatically with the form language. See Translations and Multilingual Forms.

Rules and scripts

• setVisible: shows or hides the entire widget, for example only for approved requests.
• setReadOnly: hides the New item button.
• Rules do not modify the widget's data. If the source key is another form field, the widget automatically reloads when that field changes (including via a rule).

Configuration example (JSON)

{
  "internalName": "widget_related_ukoly",
  "customLabel": "Project tasks",
  "fieldType": "relatedItems",
  "colSpan": 12,
  "defaultVisible": true,
  "relatedItemsConfig": {
    "targetListId": "00000000-0000-0000-0000-000000000000",
    "targetListTitle": "Tasks",
    "foreignKeyField": "Projekt",
    "sourceKeyField": "@itemId",
    "viewFields": ["Title", "Stav", "Termin"],
    "columnLabels": { "Title": "Task", "Stav": "Status", "Termin": "Due date" },
    "linkToItemField": "Title",
    "defaultSortField": "Termin",
    "defaultSortDirection": "asc",
    "enableSearch": true,
    "rowLimit": 25,
    "allowAddNew": true
  }
}

targetListId expects the list identifier (GUID). In the designer you pick it from a list; only enter it manually when writing JSON.

Limitations and tips

• At most rowLimit rows (up to 100) are loaded without paging. Both filtering and sorting operate only on those loaded rows, so for large relationships a matching row might not be visible. Server queries do not include sorting; default sorting is applied in the table over the loaded rows.
• Without displayed columns, Title is returned. Without custom labels, the header shows the column's internal name rather than its display name, so rename the columns.
• The user must have read permission on the target list. Otherwise the widget displays a SharePoint error.
• The widget is read-only for data: rows cannot be edited or deleted inline. Editing is available via the item detail link.
• The widget is not saved to the item, so it does not affect saving or mark the form as “dirty”.