Web Parts
Documents Rollup
Display documents from a SharePoint library in list, card, or compact layouts, with sorting, server-side pagination, category/tag filtering, and optional hand-curated quick links.
DocumentsFeature Parity: 95%
Get Documents Rollup Working in 3 Steps
10-20 minutes
Prerequisites
- Bonzai 2 package installed on your site
- A document library with files
1
Add the web part
Edit your page and add "Bonzai Documents Rollup" from the Bonzai category.
2
Pick a site and library
Choose Site Selection Mode (picker or manual URL), then pick the document library from the List picker.
3
Configure display
Choose a template (Default / Card / Compact), sort order, items per page, and which metadata fields to show, then publish.
When to Use This Web Part
Use this when you need to...
- Display recent documents on a page
- Show department-specific files
- Create a simple document gallery
- Highlight featured documents
Best page locations
- Homepage — recent documents widget
- Department pages — team documents
- Landing pages — featured file showcase
Consider alternatives when...
- • Full search experience — use Document Portal
- • Tabular data view — use Documents Table
Related web parts:
Document Portal — full search and refinementDocuments Table — tabular view with sorting
Common Configurations
Copy these ready-to-use configurations:
Recent Documents
Show recently modified documents
Best for: Homepage sidebar
Configuration
| title | Recent Documents |
| templateName | default |
| sortBy | modified |
| itemsPerPage | 10 |
| showPaging | On |
Document Cards Gallery
Grid of cards with file-type icons
Best for: Department page
Configuration
| title | Department Files |
| templateName | card |
| itemsPerRow | 4 |
| itemsPerPage | 12 |
| showPaging | On |
Compact Links List
Icon + title only, no metadata columns
Best for: Sidebar / dense navigation
Configuration
| title | Quick Documents |
| templateName | compact |
| itemsPerPage | 10 |
| chromeType | titleOnly |
Featured Documents
Show only promoted documents
Best for: Landing page
Configuration
| title | Featured Documents |
| showPromotedItems | On |
| templateName | card |
| itemsPerRow | 3 |
Short List with 'See all'
Minimal list with link to full library
Best for: Dashboard widget
Configuration
| title | Documents |
| templateName | default |
| itemsPerPage | 5 |
| showMoreText | View all documents |
| showMoreUrl | /sites/docs/Documents |
Manual Quick Links
Curated list of external or hand-picked documents
Best for: Policies landing page
Configuration
| title | Policies |
| showCustomDocumentLinks | On |
| customDocumentLinksLabel | Quick Links |
| customDocumentLinks | [{ title, url, description, openInNewTab }, ...] |
Best Practices
Sort by Modified date
Set "Sort By" to Modified to show the most recently updated documents first.
Filter with Category and Tag columns
Enable the Category/Tag filters and point them at library columns (e.g. Department, Document Type). Pre-select values to lock the web part to a subset, or leave them open so end-users can filter with runtime dropdowns.
Use Compact template for dense lists
Pick the Compact template when you only need a short stack of file links (icon + title, no metadata). It pairs well with the "Title Only" chrome type in sidebars.
Card layout for visual libraries
Use the Card template with 3-4 items per row for a scannable gallery of files. Cards render the Fluent UI file-type icon (Word, Excel, PDF, image, video, etc.), not document thumbnails.
Reference
Document Library Schema
Documents Rollup uses standard document library fields. No custom columns are required, but you can add a Promoted/Featured column to mark promoted documents.
- Select an existing document library with files.
- Optional: add a Featured (Yes/No) or PromotedState (Number) field for promoted filtering.
- If using promoted filtering, set the field value on documents you want to feature.
| Column | Type | Required | Notes |
|---|---|---|---|
| Title | Single line of text | Yes | Default library field |
| FileLeafRef | Single line of text | Yes | File name (built-in) |
| FileRef | Hyperlink | Yes | Server-relative path (built-in) |
| Modified | Date/Time | Yes | Used for sorting |
| Created | Date/Time | No | Fallback sort |
| Featured | Yes/No | No | Optional promoted filter (PromotedState also supported) |
| PromotedState | Number | No | Optional promoted filter (SharePoint system field) |
Property Pane Configuration
Title Settings
| Property | Type | Description |
|---|---|---|
title | Text | Web part title displayed above the content. Leave empty to hide the title row entirely. |
titleUrl | Text | Optional URL to make the title clickable (opens in a new tab). |
titleIconOption | Dropdown | Title icon mode: custom (default — shows the Icon Picker field) or none. |
titleIconName | Icon Picker | Fluent UI icon name. Defaults to DocumentSet. |
titleIconUrl | Text | Custom icon URL (overrides titleIconName when set). |
description | Text (Multiline, 2 rows) | Optional description below the title. |
showMoreText | Text | Text for the "Show More" footer link. Default "See all documents". |
showMoreUrl | Text | URL for the "Show More" footer link. Leave empty to hide the link. |
Data Source Settings
| Property | Type | Description |
|---|---|---|
siteSelectionMode | Dropdown | How to choose the source site: picker (Graph-powered site dropdown) or manual (type a URL). Defaults to manual. |
selectedSiteUrl | Dropdown | Site chosen from the picker (only used when siteSelectionMode is picker). Populated via Microsoft Graph /sites?search=*. |
siteUrl | Text | Manual site URL where the library is located (only used when siteSelectionMode is manual). Leave empty to use the current site. |
listName | List Picker | Document library to display files from (stores { id, title, url }; GUID is preferred so the web part is resilient to library renames). |
sortBy | Dropdown | Sort by: name, modified (default), created, or size. Name sorts ascending; other options sort descending. |
showPromotedItems | Toggle | Show only promoted/featured documents. The web part auto-discovers the first available Promoted, Featured, Featured_x003f_, or PromotedState field on the library. |
Site picker vs manual URL
The picker mode loads up to 500 sites via Microsoft Graph and is great for multi-site tenants. If Graph is unavailable or the tenant restricts
/sites search, the web part falls back to just the current site. Manual mode is always available and accepts any URL the current user can read.Dynamic Filters (Category/Tags)
| Property | Type | Description |
|---|---|---|
enableCategoryFilter | Toggle | Enable category-based filtering for this web part |
categoryFilterLabel | Text | Custom label above the category dropdown (shown only when no pre-selection is made) |
categoryFilterColumn | Dropdown / Text | Select which library column to use for Category |
selectedCategories | Multi-select | Lock the web part to specific categories. Only documents matching these values are returned from the server. When set, the runtime Category dropdown is hidden from end users. |
enableTagFilter | Toggle | Enable tag-based filtering for this web part |
tagFilterColumn | Dropdown / Text | Select which library column to use for Tags |
selectedTags | Multi-select | Lock the web part to specific tags. Only documents matching these values are returned from the server. When set, the runtime Tag dropdown is hidden from end users. |
Display Settings
| Property | Type | Description |
|---|---|---|
templateName | Dropdown | Display template: default (list with headers), card (grid of cards), or compact (dense list — file icon + title only, no headers or metadata). Default default. |
itemsPerRow | Dropdown | Items per row (2-6) for the Card template. Disabled for Default and Compact. Default 3. |
itemsPerPage | Slider (5-50, step 5) | Number of documents to display per page. Default 10. |
showPaging | Toggle | Show pagination controls. Default On. |
visibleMetadataFields | Multi-select | Which metadata to show per document: author, modified, created, fileSize, fileExtension (File Type). Default ['author', 'modified', 'fileSize']. Ignored for the Compact template, which always shows only the file icon and title. |
fixedHeight | Slider (0-800, step 50) | Fixed height in pixels for the content area (scrolls inside). 0 = auto height. Default 0. |
chromeType | Dropdown | Chrome type: none, titleOnly, borderOnly, titleAndBorder. Default titleAndBorder. |
Custom Document Links
In addition to (or instead of) pulling from a library, you can attach a hand-curated list of links that render above the document list. This is useful for external resources, cross-site shortcuts, or mixing one-off URLs alongside a library rollup.
| Property | Type | Description |
|---|---|---|
showCustomDocumentLinks | Toggle | Show the Custom Links section above the document list. Default Off. |
customDocumentLinksLabel | Text | Heading shown above the custom links (default "Quick Links"). Hidden if empty. |
customDocumentLinks | Collection | List of manual links. Each entry has title (required), url (required), description (optional), and openInNewTab (optional boolean, default true). File icons are auto-detected from the URL extension. |
File Type Icons
Documents Rollup renders a Fluent UI icon per file based on its extension. No configuration is required. Supported categories include Microsoft Office (Word, Excel, PowerPoint, OneNote, Visio, Project, Publisher), PDF, plain text, images (jpg/png/gif/svg/webp/tiff), video (mp4/mov/avi/wmv/mkv/webm), audio (mp3/wav/flac/aac/wma), archives (zip/rar/7z/tar/gz), code (html/css/js/ts/json/xml/sql/py/java/ cs/cpp/php/go/swift/kt/md/yaml), email (msg/eml), and system files (exe/dll/msi). Unknown extensions fall back to a generic Document icon.
Pagination & Data Loading
- Pagination uses SharePoint's server-provided
@odata.nextLinkrather than$skip, which is unreliable when combined with$filter. - The web part caches each page locally, so navigating back to a previously loaded page is instant. Changing the library, site, sort order, promoted toggle, filter columns, items-per-page, or admin pre-filters invalidates the cache and refetches from page 1.
- A query tries progressively simpler
$selectfield combinations so the rollup still works on libraries missingFile_x0020_Size,FileSizeDisplay, or expandedAuthor. - Total item count is only fetched when no filters are active (
showPromotedItemsoff and no category/tag pre-filters). Filtered queries show the current range (e.g.11-20) without a grand total.
Features Checklist
- ✅ Default (list), Card (grid), and Compact display templates
- ✅ Dual-mode site selection — Microsoft Graph site picker or manual URL
- ✅ List Picker with GUID persistence (rename-resilient)
- ✅ Multiple sort options (Name, Modified, Created, Size)
- ✅ Server-paged results via
@odata.nextLinkwith page caching - ✅ Promoted / featured items with auto-discovered field (
Promoted,Featured,Featured_x003f_,PromotedState) - ✅ Dynamic category and tag filters with server-side pre-filtering and runtime user dropdowns
- ✅ Custom label for the runtime category dropdown
- ✅ Configurable metadata fields per item (Author, Modified, Created, File Size, File Type)
- ✅ Configurable items per row for Card template (2-6)
- ✅ Fixed-height scrollable container
- ✅ Chrome type control (none / title only / border only / title and border)
- ✅ Custom title with Fluent UI icon or custom icon URL, and optional title link
- ✅ "Show more" footer link
- ✅ Custom Document Links section (curated manual links with auto file-type icons)
- ✅ Rich file-type icon mapping (Office, PDF, images, video, audio, archives, code, email)
- ✅ Progressive
$selectfallback for libraries with non-standard schemas