Add a custom banner message to your SharePoint Online modern sites. Allows a site owner to modify the text, font size, colors and height of the banner. Specify a start date to control when the banner is visible to members of a site. Experimental support for setting the custom action host property 'preAllocatedApplicationCustomizerTopHeight' to avoid the page shifting upon load.
Built using a SharePoint Framework Application Customizer Extension with the Top placeholder. Customization settings are saved into the ClientSideComponentProperties of the host custom action. Supports adding at the site-scope or web-scope.
View as user
View as site admin
View as site admin with a scheduled start date
- App Catalog: Ensure the App Catalog is setup in your SharePoint Online tenant
- PnP PowerShell or Office 365 CLI: Ensure you have the latest version of the SharePointPnPPowerShellOnline module installed. Alternatively, you can use the Office 365 CLI.
-
Download the SPFx package message-banner.sppkg file from Github (or clone the repo and build the package yourself)
-
Upload sppkg file to the 'Apps for SharePoint' library in your Tenant App Catalog
-
Click the 'Make this solution available to all sites in your organization' checkbox and then click Deploy
-
Register the SPFx extension on your target SharePoint site(s) using one of the methods below.
Connect-PnPOnline -Url "https://tenant.sharepoint.com/sites/target" #Site Collection Scoped Add-PnPCustomAction -Title "CustomMessageBanner" -Name "CustomMessageBanner" -Location "ClientSideExtension.ApplicationCustomizer" -ClientSideComponentId "1e2688c4-99d8-4897-8871-a9c151ccfc87" -ClientSideComponentProperties "{`"message`":`"Sample site-scoped message banner text.`"}" -Scope Site #Web Scoped Add-PnPCustomAction -Title "CustomMessageBanner" -Name "CustomMessageBanner" -Location "ClientSideExtension.ApplicationCustomizer" -ClientSideComponentId "1e2688c4-99d8-4897-8871-a9c151ccfc87" -ClientSideComponentProperties "{`"message`":`"Sample web-scoped message banner text.`"}" -Scope Web
o365 spo login https://tenant.sharepoint.com/sites/target #Site Collection Scoped o365 spo customaction add --url 'https://tenant.sharepoint.com/sites/target' --title 'CustomMessageBanner' --name 'CustomMessageBanner'--location 'ClientSideExtension.ApplicationCustomizer' --clientSideComponentId '1e2688c4-99d8-4897-8871-a9c151ccfc87' --clientSideComponentProperties '{\"message\":\"Sample site-scoped message banner text.\"}' --scope Site #Web Scoped o365 spo customaction add --url 'https://tenant.sharepoint.com/sites/target' --title 'CustomMessageBanner' --name 'CustomMessageBanner'--location 'ClientSideExtension.ApplicationCustomizer' --clientSideComponentId '1e2688c4-99d8-4897-8871-a9c151ccfc87' --clientSideComponentProperties '{\"message\":\"Sample web-scoped message banner text.\"}' --scope Web
Follow the same steps as installation. Overwrite the existing package in the 'Apps for SharePoint' library when uploading the new package.
Tip: Be sure to check-in the sppkg file after the deployment if it is left checked-out.
This solution is deployed by registering a custom action on your site(s) at either the site or web scopes.
The banner settings are saved into the ClientSideComponentProperties on the custom action. The specific properties are below which can be set programmatically using one of the installation methods described above.
| Property Name | Default Value | Description |
|---|---|---|
| message | "This is a sample banner message. Click the edit icon on the right side to update the banner settings." |
Text or HTML. Supports {siteUrl} and {webUrl} tokens. |
| textColor | "#333333" |
Text color shown within the banner. |
| backgroundColor | "#ffffc6" |
Background color of the banner. |
| textFontSizePx | 14 |
Font size of the banner text in pixels. |
| bannerHeightPx | 30 |
Height of the banner in pixels. |
| visibleStartDate | null |
Optional. Date string at which the banner message should be shown to members and visitors of the site. Message will always be visible to admins. |
| disableSiteAdminUI | false |
Optional. Boolean flag to disable the site administrator user interface (edit icon). Additionally, if the visibleStartDate property is set to a future date, site administrators will no longer see the banner with the future visibility date badge. |
| enableSetPreAllocatedTopHeight | false |
Optional. Boolean flag to enable setting the host property 'preAllocatedApplicationCustomizerTopHeight' when saving new banner height within the settings panel. This flag signals SharePoint to pre allocate the banner location height server-side to avoid the page shifting down during render. |
Additionally, if you are a site owner or site collection administrator, you can customize the banner using the 'edit' pencil icon via the browser.
-
Unregister the SPFx extension on your target SharePoint site(s) using one of the methods below.
Connect-PnPOnline -Url "https://tenant.sharepoint.com/sites/target" #Site Collection Scoped Get-PnPCustomAction -Scope Site | Where-Object { $_.ClientSideComponentId -eq "1e2688c4-99d8-4897-8871-a9c151ccfc87" } | Remove-PnPCustomAction #Web Scoped Get-PnPCustomAction -Scope Web | Where-Object { $_.ClientSideComponentId -eq "1e2688c4-99d8-4897-8871-a9c151ccfc87" } | Remove-PnPCustomAction
o365 spo login https://tenant.sharepoint.com/sites/target #Site Collection Scoped - Get Custom Action ID o365 spo customaction list --url 'https://tenant.sharepoint.com/sites/target' --scope Site #Site Collection Scoped - Remove by Custom Action ID o365 spo customaction remove --id '<CUSTOM ACTION ID OF BANNER FROM PREVIOUS STEP>' --url 'https://tenant.sharepoint.com/sites/target' --scope Site #Web Scoped - Get Custom Action ID o365 spo customaction list --url 'https://tenant.sharepoint.com/sites/target' --scope Web #Web Scoped - Remove by Custom Action ID o365 spo customaction remove --id '<CUSTOM ACTION ID OF BANNER FROM PREVIOUS STEP>' --url 'https://tenant.sharepoint.com/sites/target' --scope Web
- Follow steps to uninstall the SPFx extension from all sites.
- Delete the
message-banner.sppkgfile from the 'Apps for SharePoint' library in your Tenant App Catalog.
Microsoft provides programming examples for illustration only, without warranty either expressed or implied, including, but not limited to, the implied warranties of merchantability and/or fitness for a particular purpose. We grant You a nonexclusive, royalty-free right to use and modify the Sample Code and to reproduce and distribute the object code form of the Sample Code, provided that You agree: (i) to not use Our name, logo, or trademarks to market Your software product in which the Sample Code is embedded; (ii) to include a valid copyright notice on Your software product in which the Sample Code is embedded; and (iii) to indemnify, hold harmless, and defend Us and Our suppliers from and against any claims or lawsuits, including attorneys' fees, that arise or result from the use or distribution of the Sample Code.