Web Parts
Document Portal
Full-featured document search with typeahead suggestions, popular searches, favourites, and multiple view modes.
DocumentsFeature Parity: 85%
Get Document Portal Working in 3 Steps
15-30 minutes
Prerequisites
- Bonzai 2 package installed on your site
- Documents in a SharePoint library (indexed by search)
1
Add the web part to a full-width section
Edit the page, add a full-width section, click + and search for "Document Portal".
2
Configure result source (optional)
Open the property pane and set the Result Source to a specific search result source, or leave empty for default.
3
Publish and test
Save and publish the page. Favourites, document previews, popular searches, hover preview, and the List/Grid toggle are all on by default — the full experience is ready immediately.
When to Use This Web Part
Use this when you need to...
- Create a dedicated document search center
- Enable users to find documents across multiple libraries
- Provide document filtering by type, author, date, or custom metadata
- Allow users to bookmark frequently accessed documents
- Build a department-specific document repository page
Best page locations
- Document Center page — dedicated full-page experience
- Department landing page — filtered to department documents
- Knowledge base page — searchable documentation library
- Policies page — regulatory and policy documents
Consider alternatives when...
- • Displaying a fixed list of specific documents — use Documents Rollup
- • Showing recent documents only — use Documents Rollup with date filter
- • Simple file list without search — use Documents Table
Related web parts:
Documents Rollup — simple document list or cardsDocuments Table — tabular view without searchFavourite Documents — bookmarked documents only
Documents-only search
Document Portal always scopes search to documents (files). This ensures consistent results and avoids returning pages, list items, or other non-document content. No toggle is needed — the behaviour is built in.
Search Scope
The Search Scope dropdown offers three options:
- Current Site (default) — searches all documents in the current site.
- Specific Library — narrows results to one document library on the chosen site. Useful for department or product portals that should only surface documents from a single library.
- All Sites — searches documents across every site the user has access to (tenant-wide).
For the Specific Library and All Sites options, you also pick a Site Selection Mode — either choose a site from a Microsoft Graph-powered picker or enter a site URL manually.
Category & Tag Filters
Document Portal can surface two extra dropdown filters above the search box, each backed by a managed property:
- Category filter — toggle on
enableCategoryFilter, pick a managed property (defaults toContentType), and optionally pre-select categories in the property pane to scope the portal for every visitor. - Tag filter — toggle on
enableTagFilter, pick a managed property (defaults toowstaxIdMetadataAllTagsInfo), and optionally pre-select tags.
Pre-selected values from the property pane are always applied as refinement filters, while end users can further narrow results using the dropdowns at runtime.
Hover preview card
In List view, hovering a row shows a lightweight preview card (toggled via
showHoverPreview, on by default). Clicking the preview icon still opens the full preview through the standard document viewer URL.Typeahead can open documents directly
Enable
typeaheadOpenDocuments (Advanced page) so that clicking a typeahead suggestion jumps straight to the document instead of populating the search box. Pair it with a curated set of Typeahead Fieldsfor the best experience.Step-by-Step Configuration
1
Create a new page for your Document Portal
Go to Site Pages, create a new page named "Document Center" or "Documents". Use a single-column layout for best results.
Document Portal works best as the main content on a dedicated page.
2
Add a full-width section
In edit mode, add a new section with a full-width layout. This gives the portal maximum space.
3
Add the Document Portal web part
Click the + button, search for "Document Portal", and add it to the full-width section.
4
Configure the Result Source (optional)
Open the property pane and set the Result Source to a specific SharePoint search result source name or ID, or leave empty for the default search.
Result sources control which content is searched. Ask your admin for available result source names.
5
Configure typeahead (optional)
On the Advanced page, pick managed properties in the "Typeahead Fields" multi-select to control what appears in suggestions. Optionally enable "Typeahead opens documents" so clicking a suggestion opens the document directly.
Column and typeahead multi-selects populate from the managed properties available for your Result Source — they load asynchronously the first time you open the property pane.
6
Choose the default view
Select "Default View" as List or Grid to control how search results display. When the List/Grid view toggle is turned off, the alternate view's column picker hides automatically.
7
Review the Sections page
Favourite Documents, Popular Searches, document previews, and the view toggle are all on by default. Switch on "Search-only Mode" for a minimal UI that hides popular searches, favourites, custom links, the filters panel, and the view toggle.
8
Set items per page
Configure how many documents appear per page using the "Items Per Page" slider (10–100, step 5).
9
Publish and test search
Save and publish. Test by searching for known documents and verifying results appear correctly.
Common Configurations
Copy these ready-to-use configurations:
Company Document Center
Full-featured search for all company documents
Best for: Dedicated document search page
Configuration
| title | Document Center |
| defaultView | list |
| showFavouriteDocuments | On |
| showDocumentPreviews | On |
| showPopularSearches | On |
| itemsPerPage | 30 |
Department Documents
Using a specific result source for a team
Best for: Team or department page
Configuration
| title | HR Documents |
| resultSource | HR Documents Result Source |
| defaultView | grid |
| showFavouriteDocuments | On |
| itemsPerPage | 20 |
Policy Repository
Filtered to policy documents with search filters
Best for: Compliance and policy pages
Configuration
| title | Policies & Procedures |
| resultSource | Policies |
| showFavouriteDocuments | On |
| showDocumentPreviews | On |
| sortOrder | name |
My Documents Quick Access
Favourites-focused for personal bookmarks
Best for: Personal dashboard pages
Configuration
| title | My Documents |
| showFavouriteDocuments | On |
| enableWildcardSearch | On |
| itemsPerPage | 15 |
Best Practices
Allow time for search indexing
Newly uploaded documents may take 15-30 minutes to appear in search results. SharePoint search crawls content periodically, not in real-time.
Use specific search scopes for performance
Set Search Scope to "Specific Library" to narrow results to a single document library. This improves query speed and gives users more relevant results.
Add metadata for better refinement
Documents with rich metadata (document type, department, project) enable more useful refinement filters. Encourage content owners to tag documents.
Verify permissions before publishing
Document Portal respects SharePoint permissions. Users will only see documents they have access to. Test with a regular user account before launch.
Reference
Technical details for developers and advanced users.
FavouriteDocuments List Schema (optional)
The favourites section stores bookmarks in a SharePoint list named FavouriteDocuments on the effective site (the one resolved from the Search Scope settings). Create this list only if you enable "Show Favourite Documents".
- Create a list named FavouriteDocuments on the same site the portal searches.
- Add the required columns below (the built-in Author column is used to scope rows per user).
- Ensure users have Contribute permissions to save favourites.
| Column | Type | Required | Notes |
|---|---|---|---|
| Title | Single line of text | Yes | Document title |
| DocumentPath | Single line of text (URL) | Yes | Document URL |
| DocumentId | Single line of text | Yes | Search DocId / UniqueId |
| FileExtension | Single line of text | Yes | File extension (e.g., pdf, docx) |
| AddedDate | Date/Time | Yes | Saved when favourite is added |
PopularSearches List Schema (optional)
Popular searches are aggregated in a SharePoint list named PopularSearches on the same effective site. Create it only if you enable "Show Popular Searches". Each executed search either increments SearchCount for an existing entry or creates a new one.
| Column | Type | Required | Notes |
|---|---|---|---|
| Title | Single line of text | Yes | The search query text |
| SearchCount | Number | Yes | Number of times this query was run |
| LastUsed | Date/Time | Yes | Last time the query was executed |
Permissions for popular searches
Recording a popular search is best-effort. If users lack Contribute access to the PopularSearches list, the call fails silently and search results are still returned.
Related Components
Document Portal works with companion components:
- Favourite Documents: User bookmarks for documents (integrated into Document Portal)
- Documents Rollup: For displaying a fixed list of documents without search
- Documents Table: For tabular document display
Property Pane Configuration
The property pane is split across two pages. Page 1 covers Search Scope, Search Settings, and Results Display. Page 2 covers Sections, Category & Tag Filters, Title & Navigation, Appearance, and Advanced.
Page 1 — Search Scope
| Property | Type | Default | Description |
|---|---|---|---|
searchScope | Dropdown | currentSite | Current Site, Specific Library, or All Sites |
siteSelectionMode | Dropdown | manual | Select from available sites (picker) or enter a site URL manually. Shown only when searchScope is not Current Site. |
selectedSiteUrl | Dropdown | — | Site dropdown (picker mode; populated via Microsoft Graph /sites?search=*) |
siteUrl | Text | — | Manual site URL (manual mode). Leave empty for the current site. |
selectedLibraryUrl | Dropdown | — | Document library (server-relative URL) to scope results to. Shown only when searchScope = Specific Library. |
resultSource | Text | — | SharePoint Search result source name or ID (optional) |
Page 1 — Search Settings
| Property | Type | Default | Description |
|---|---|---|---|
searchLabelOption | Dropdown | searchDocuments | Preset placeholder (Search documents…, Search files…, etc.) or Custom |
searchLabel | Text | — | Custom placeholder text (used when searchLabelOption = custom) |
enableWildcardSearch | Toggle | On | Automatically wraps queries in wildcards (*term*) |
itemsPerPage | Slider (10–100, step 5) | 30 | Number of results per page |
Page 1 — Results Display
| Property | Type | Default | Description |
|---|---|---|---|
defaultView | Dropdown | list | Default view mode: List or Grid |
listViewColumns | Multi-select | — | Managed properties shown as columns in List view. Falls back to Created, LastModifiedTime, Author when empty. |
gridViewColumns | Multi-select | — | Managed properties shown on Grid cards. Falls back to LastModifiedTime, Author when empty. Hidden when Grid view is unreachable. |
visibleMetadataFields | Multi-select | ["author", "modified"] | Which built-in metadata fields show on each result. Options: author, modified, created, fileSize, fileExtension, contentType, siteName, description, category, tags. |
showMetadataChips | Toggle | On | Show metadata chips on results |
showSortDropDown | Toggle | On | Show sort dropdown to end users |
sortOrder | Dropdown | relevance | Default sort: Relevance, Date, or Name |
showViewToggle | Toggle | On | Show the List/Grid view toggle. Disabled when searchOnlyMode is on. |
showFiltersPanel | Toggle | On | Show the filters panel when refiners exist. Disabled when searchOnlyMode is on. |
trimDuplicates | Toggle | Off | Remove duplicate results from search |
showHoverPreview | Toggle | On | Show the hover preview card in List view. Hidden when List view is unreachable. |
showDocumentPreviews | Toggle | On | Enable the preview icon and document preview panel |
Page 2 — Sections
| Property | Type | Default | Description |
|---|---|---|---|
searchOnlyMode | Toggle | Off | Minimal UI preset. Hides popular searches, favourites, custom links, the filters panel, and the view toggle. |
showResults | Toggle | On | Show search results section (always treated as on in Search-only mode) |
showPopularSearches | Toggle | On | Show popular searches section. Disabled when searchOnlyMode is on. |
showFavouriteDocuments | Toggle | On | Show favourite documents section. Disabled when searchOnlyMode is on. |
favouriteDocumentsLabel | Text | Favourite Documents | Label for the favourites section. Only visible when Show Favourites is on. |
showCustomDocumentLinks | Toggle | Off | Show a custom links section. Disabled when searchOnlyMode is on. |
customDocumentLinksLabel | Text | Custom Documents | Label for the custom links section. Only visible when showCustomDocumentLinks is on. |
customDocumentLinks | Collection Data | [] | Manually managed links. Each item has title, url, description, and openInNewTab. |
Page 2 — Category & Tag Filters
| Property | Type | Default | Description |
|---|---|---|---|
enableCategoryFilter | Toggle | Off | Enable the runtime Category dropdown. Disabled when searchOnlyMode is on. |
categoryFilterProperty | Dropdown / Text | ContentType | Managed property that drives the Category dropdown |
selectedCategories | Multi-select | [] | Pre-selected category values. Applied as baseline refinement filters for every user. |
enableTagFilter | Toggle | Off | Enable the runtime Tag dropdown. Disabled when searchOnlyMode is on. |
tagFilterProperty | Dropdown / Text | owstaxIdMetadataAllTagsInfo | Managed property that drives the Tag dropdown |
selectedTags | Multi-select | [] | Pre-selected tag values. Applied as baseline refinement filters for every user. |
Page 2 — Title & Navigation
| Property | Type | Default | Description |
|---|---|---|---|
title | Text | — | Web part title (leave empty to hide the title row) |
titleUrl | Text | — | URL to make the title clickable |
titleIconOption | Dropdown | custom | Title icon mode: Select Icon or None |
titleIconName | Icon Picker | DocumentSearch | Fluent UI icon. Hidden when titleIconOption = none. |
titleIconUrl | Text | — | Custom icon URL (overrides the icon name) |
Page 2 — Appearance
| Property | Type | Default | Description |
|---|---|---|---|
chromeType | Dropdown | none | Chrome type: None, Title Only, Border Only, Title and Border |
fixedHeight | Slider (0–800, step 50) | 0 | Fixed container height in pixels. 0 means auto (no fixed height). |
resultsMaxHeight | Slider (300–900, step 20) | 480 | Maximum height of the results region |
Page 2 — Advanced
| Property | Type | Default | Description |
|---|---|---|---|
typeaheadFields | Multi-select | [] | Managed properties shown in typeahead suggestions. Populated from the Result Source. |
typeaheadOpenDocuments | Toggle | Off | Clicking a typeahead suggestion opens the document directly |
searchFilterFields | Multi-select | [] | Managed properties available as refiners in the filters panel |
searchHeight | Slider (32–56, step 2) | 40 | Search box height in pixels |
resultsFontSize | Slider (12–18, step 1) | 14 | Results text font size in pixels |
rowHeight | Slider (36–72, step 4) | 44 | List view row height in pixels |
gridCardSize | Slider (160–320, step 10) | 220 | Grid view card width in pixels. Hidden when Grid view is unreachable. |
description | Text (Multiline) | — | Web part description |
helpUrl | Text | — | Help documentation URL |
Features Checklist
- ✅ Full-text document search (always scoped to files via
documentsOnly) - ✅ Search scope across Current Site, Specific Library, or All Sites
- ✅ Typeahead suggestions with optional “open document on click”
- ✅ Popular searches section (backed by a SharePoint list)
- ✅ Favourite documents integration (per-user, backed by a SharePoint list)
- ✅ Custom Document Links section (manually curated links)
- ✅ Category & Tag filter dropdowns (with admin pre-selection support)
- ✅ Filters panel (refiners) driven by selected managed properties
- ✅ List and Grid view modes with independent column configuration
- ✅ Hover preview card on List rows + full document preview
- ✅ Configurable sort options (Relevance, Date, Name)
- ✅ Wildcard search, duplicate trimming, and pagination
- ✅ Search-only Mode preset for minimal UI
- ✅ Fine-grained appearance controls (search height, row height, grid card size, font size)
Migration from Classic
| Aspect | Classic | Modern |
|---|---|---|
| Technology | JSOM + CAML queries | SPFx + SharePoint Search REST API |
| Typeahead | Brick configuration | Configured via the typeaheadFields multi-select of managed properties |
| View Modes | List only | List and Grid view options with per-view column pickers |
| Favourites | Separate web part | Integrated section (toggle), backed by the FavouriteDocuments list |
| Popular Searches | Not available | Built-in section (toggle), backed by the PopularSearches list |
| Refiners | Fixed set | Managed-property-driven filter panel, plus dedicated Category & Tag dropdowns |
| Search scope | Current site only | Current Site, Specific Library, or All Sites |