Related Documents

Documents from a library related to the item, mapped by folder or metadata.

Widget description: relatedDocuments

The widget displays a table of documents from a document library that belong to the current item, allowing users to open, preview, and upload new files. Documents are associated with an item in two ways: by folder (each item has its own subfolder in the library) or by metadata (a library column stores the item's key). It is a virtual widget: files remain in the library and nothing is saved to the item. For general item attachments, use the Attachments field; for linking to another list, use Related Items.

Adding to the form

1. On the Widgets tab, select Related Documents (subtitle “Widget · document library”) and drag it into a section, or click “+”.
2. In the inspector, select the Target document library. Only document libraries on the site are offered.
3. Choose the File mapping mode and fill in its settings (see below).
4. Select the displayed columns and configure preview sizes.

Until a library is selected, the widget displays “Widget is not configured” in the form.

Inspector settings

Deleting files is off by default; turn it on with the allowDelete option. After confirmation the file is moved to the site recycle bin and the list refreshes. If the user has no permission to delete in the library, SharePoint rejects the action and the widget shows the error; see Limitations and tips.

Mapping modes

Folder by item ID (folder)

Item documents are stored in a folder named after the source key value: <library>/<subfolder>/<key>. For example, for an item with ID 42 and subfolder Projects, this is Projects/42. The widget creates the folder on first upload and overwrites any existing file with the same name. It only reads files directly inside that folder, not in subfolders; library columns of type Person and Lookup (including multi-value) are displayed as text. A non-existent folder is shown as an empty list.

This mode is the simplest and requires no extra column in the library. It does not use a filter, so it is not affected by the 5,000-item threshold.

Metadata column (metadata)

Documents can reside anywhere in the library and are linked to the item by the value of the foreign key column. On upload, the widget saves the file to the library root and populates the foreign key column: with the item ID for a lookup column, or with the key value for a text column. Foreign key column types (lookup, number, text) are handled the same way as in Related Items.

Metadata mode is subject to the unindexed column check. Without a selected foreign key column, metadata mode behaves like folder mode when reading documents, so always select a foreign key column.

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

Metadata mode only. If the foreign key column is unindexed and the library has over 5,000 items, SharePoint would reject the query (List View Threshold). Therefore, the widget:

• In the designer: displays a warning “Column … is not indexed” below the foreign key picker with an Index column button that indexes the column in the library (requires library administrator permissions).
• At runtime: does not send the query and displays an error asking for the column to be indexed. The same message is shown if SharePoint returns a threshold error.

Details and recommendations are the same as in Related Items.

Runtime behavior

• New: with key @itemId, the item does not have an ID yet; the widget shows “Related records will be available after the item is saved for the first time” and upload is disabled. With another source key, documents load as soon as the key field has a value.
• Edit: document table, count in the header, Refresh button, filter, and upload drop zone.
• Display: the same table without the upload zone. The Properties button remains if enabled.
• Upload: drag files into the “Drag files here or click to upload to library” area, or click it to browse. Multiple files can be uploaded at once. Each file is saved directly to the library without waiting for the form to be saved. File names with disallowed characters (~ " # % & * : < > ? / \ { | }) are rejected. A file with the same name is overwritten.
• File name: clicking opens the document in a preview dialog. Hovering shows a quick preview: a thumbnail for images, an embedded preview for Office and PDF files, plus size, modified date, and last editor. For types without a preview, only metadata is shown. After the mouse leaves, the preview stays open for about 1 s so you can move into it (since 1.32.0).
• Properties: the button opens the document's properties (library item form) in a dialog. A document without an ID (for example in a folder without a list item) has the button disabled. When you edit and save properties in the dialog, the dialog closes and the table refreshes.
• Filter (“Filter documents…”) searches in name, editor, date, and custom columns and shows “Found: x of y”. You can resize column widths by dragging the edge of the header.
• File size is displayed in human-readable units (KB, MB), and dates follow the form language.

Resizing the quick preview: there is a handle in the bottom-right corner of the preview. Drag it to change the width (240 px to 92% of the window) and the content height (140 px to 75% of the window); the preview stays open while dragging. The handle also works from the keyboard (Tab): arrow keys resize by 20 px, Shift + arrow by 80 px. Double-clicking the handle restores the default size from the widget settings. The chosen size is remembered in the browser (shared by all documents). The Pin / enlarge button in the preview header opens the document in the large dialog.

Text translations

The title (customLabel) and column labels (columnLabels, keyed by name, size, modified, editor, or the custom column's internal name) can be translated. Without a custom label, standard columns switch automatically with the form language, while custom columns display their internal name. See Translations and Multilingual Forms.

Rules and scripts

• setVisible: shows or hides the widget.
• setReadOnly: disables upload (the drop zone is hidden).
• If the source key is another form field, the widget reloads documents whenever that field changes.

Configuration example (JSON)

Folder mode:

{
  "internalName": "widget_related_docs",
  "customLabel": "Project documents",
  "fieldType": "relatedDocuments",
  "colSpan": 12,
  "defaultVisible": true,
  "relatedDocumentsConfig": {
    "libraryId": "00000000-0000-0000-0000-000000000000",
    "libraryTitle": "Project Documents",
    "mappingMode": "folder",
    "sourceKeyField": "@itemId",
    "folderPathTemplate": "Projects",
    "viewFields": ["name", "size", "modified", "editor"],
    "columnLabels": { "name": "File", "modified": "Modified", "editor": "Modified by" },
    "allowDisplayView": true,
    "allowUpload": true,
    "enableHoverPreview": true,
    "hoverPreviewWidth": "480px",
    "hoverPreviewHeight": "320px",
    "previewDialogWidth": "92%",
    "previewDialogHeight": "90%"
  }
}

Metadata mode (only changed properties):

{
  "relatedDocumentsConfig": {
    "libraryId": "00000000-0000-0000-0000-000000000000",
    "mappingMode": "metadata",
    "sourceKeyField": "@itemId",
    "foreignKeyField": "Projekt",
    "viewFields": ["name", "modified"]
  }
}

Limitations and tips

• Deleting (allowDelete) moves the file to the site recycle bin. The widget does not know in advance whether the user may delete, so the button is shown to everyone who can edit the form, and SharePoint's error is displayed when the permission is missing. Only a file inside the configured library can be deleted.
• The document table has no column sorting: order is determined by SharePoint. Filtering works.
• In folder mode, only files directly inside the item's folder are read, not in subfolders. The folder is created on the first upload.
• In folder mode, the user needs permission to create folders and add files; in metadata mode, permission to edit the newly uploaded file (to populate the foreign key column).
• In metadata mode, the foreign key column must exist in the library. The column picker includes text, choice, number, lookup, and yes/no types.
• Custom columns of type Person and Lookup (including multi-value) are loaded via $expand and shown as text (name, lookup value, comma-separated for multiple values). The inspector column picker also includes these types and date. If library column metadata cannot be read, the query runs without expansion. Audit columns (Created By, Modified By, Created, Modified, ID, Attachments) are at the bottom under the “System columns” divider.
• Office and PDF previews use SharePoint's embedded viewer. For other file types (such as archives), there is no embedded preview; only file details are shown and the document opens via dialog.
• Files are uploaded immediately, even if you later close the form without saving.