Files & Documents

In Pega, Files & Documents are unlike attachments in consumer applications. It is critical that all data is added to the queue before any content is uploaded into Files & Documents. This is important for auditing.

The Files & Documents widget works for a single file as well as for multiple files.

Single file

The single file widget option may or may not the drag-and-drop utility, depending on the user’s device. This component appears as a resting element, changes form upon hover, uses an uploading icon (when replacing the drag-and-drop action), displays an error message when unable to upload, and a success message with a default read-only state.

Common reasons for errors may include file size limit exceeded, corrupt files or insecure files.

The success message displays an ellipsis icon button that contains additional actions (e.g., preview, download, edit or delete). In some cases, this ellipsis button, known as the “More actions” menu may be restricted for security reasons. The success message includes the filetype icon, an optional category for the attachment, relative time of upload, the creator of the upload, and ID (if available).

Multiple file

The multiple file widget option keeps the drag-and-drop utility, depending on the user’s device and follows the same patterns as the single file Attachment. In upload mode, the metadata is the file name. The success message will include the list of all files uploaded.

Drag-and-drop is not available on mobile.

The Files & Documents component may sit inline where enough space is available. The user only needs to access the file browser, which opens in a modal.

When there is not enough space to include the Files & Documents component inline, there are other ways of attaching files beyond the file browser. The drag-and-drop region could be extended to handle other actions. This approach is used in the default Files & Documents widget.

Tabs must be allowed to be disabled within authoring, as well as linking/creating new documents. All submit/create actions must be disabled until enough details are provided by the user for submission.

Attachments may be displayed as a list or as individual cards.


In list form, all attachments display one action: either the only action (e.g., edit) or a menu of allowed actions. Swipe support may show additional actions. See Tables and Lists for more details.


Tile form is typically used in content of attaching to a chat conversation or a table row. Similar to the list display, there is one action per item (typically a remove button). All tiles must be the same width. The maximum width of each card is up to 250 px. The minimum width is 150 px.