Web Parts
Important Messages
Display announcements and alerts with targeting, dismissable options, and date-based activation.
CommunicationFeature Parity: 95%
Get Important Messages Working in 3 Steps
15-30 minutes
Prerequisites
- Bonzai 2 package installed on your site
- Important Messages SharePoint list created (see schema below)
1
Create the Important Messages list
Create a SharePoint list with the required columns: Title, Body, Category, StartDate, EndDate.
2
Add the web part to your page
Edit the page, click +, search for "Important Messages", and add it to a section.
3
Select your list and configure
Open the property pane, select your list from the dropdown, configure options, and publish.
When to Use This Web Part
Use this when you need to...
- Announce system maintenance or outages
- Share company-wide important updates
- Display emergency notifications
- Communicate policy changes or deadlines
- Target specific messages to departments or locations
Best page locations
- Homepage — at the top for maximum visibility
- Department pages — for team-specific announcements
- Landing pages — for contextual alerts
- Any page header — first thing users see
Consider alternatives when...
- • Long-form news articles — use News Rollup instead
- • Permanent content — messages should be time-limited
- • Interactive content — this is read-only
Related web parts:
News Rollup — detailed news articles with imagesContent Cards — static informational tiles
Message Categories
Important Messages supports four visual styles based on the Category field:
InfoGeneral announcements and updates
WarningImportant notices requiring attention
ErrorUrgent alerts and emergencies
SuccessPositive updates and confirmations
Styling and Theme
- Message background uses the site accent color (
--bonzai-accentCSS custom property set by Theme Manager) for a banner-style appearance. - Falls back to Bonzai orange (
#d83b01) when no accent color is configured. - Foreground text color is computed automatically using WCAG luminance so contrast always meets readability thresholds.
- Icons are based on the selected Category (Info, Warning, ErrorBadge, Completed — Fluent UI icons).
- Dismiss action is hidden automatically for any message whose
AllowDismissalfield is set to No.
Step-by-Step Configuration
1
Create the Important Messages SharePoint list
Go to Site Contents → New → List. Name it "Important Messages". Add the columns from the schema below.
Use the list template script if available in your Bonzai deployment package.
2
Add your first message to the list
Open the list, click "New", fill in the Title, Body (rich text), Category, StartDate, and EndDate fields.
3
Edit the page and add the web part
Navigate to your target page, click Edit, click the + button in a section, and search for "Important Messages".
4
Select your list in the property pane
Click the pencil icon on the web part, then select your list from the List dropdown picker.
5
Configure display options
Set the title (optional), adjust "Max Messages to Show" slider (1-10), and optionally set a fixed height.
6
Enable content targeting (optional)
Toggle on Content Targeting and set TargetAudience values to SharePoint group names.
7
Publish and test
Save and publish the page. Verify messages appear with correct styling based on Category.
Common Configurations
Copy these ready-to-use configurations:
Homepage Alert Banner
Critical alerts at the top of the homepage
Best for: Homepage, full-width above content
Configuration
| Title | Announcements |
| Max Messages to Show | 3 |
| Content Targeting | Off |
| Fixed Height | 0 (auto) |
Department Notices
Targeted messages for specific teams
Best for: Department landing pages
Configuration
| Title | HR Updates |
| Content Targeting | Enabled |
| Target Audience | HR Team (SharePoint group) |
| Max Messages to Show | 5 |
Emergency Broadcast
High-visibility error alerts
Best for: Site-wide emergency communication
Configuration
| Title | ⚠️ Alert |
| Category | Error |
| Max Messages to Show | 1 |
| Fixed Height | 150 |
Regional Updates
Location-specific announcements
Best for: Regional office pages
Configuration
| Title | Local News |
| Content Targeting | Enabled |
| Max Messages to Show | 5 |
| Site URL | (current site) |
Best Practices
Use date ranges for automatic activation
Set StartDate and EndDate on all messages so they automatically appear and disappear. This eliminates the need to manually manage active messages.
Reserve Error category for true emergencies
Using the Error category too often trains users to ignore it. Save red styling for genuine urgent situations only.
Blank titles hide the header row
If you leave the Title field blank, the header row (title + icon) is hidden for a cleaner banner.
Use targeting or separate lists for contexts
Use TargetAudience values (SharePoint group names) for audience-specific messages, or create separate lists per department when you need completely different message sets.
Always set end dates
Messages without EndDate may display indefinitely. Set realistic end dates to keep content fresh and relevant.
AllowDismissal is a list field
The ability to dismiss individual messages is controlled per-message via the
AllowDismissalfield in the SharePoint list, not a web part property. Set this to "No" for critical messages that should always be visible.Network errors retry automatically
Network-related failures whose error message contains
network, timeout,ECONNRESET, ETIMEDOUT, or Failed to fetch are retried up to twice with a one-second delay before surfacing an error. Server errors (HTTP 500/502/503/504), network errors, dismissal failures, and unknown errors surface a "Retry" button instead of retrying automatically. Permission, not-found, missing-column, and invalid-configuration errors fail fast with actionable guidance and no Retry button.Reference
Technical details for developers and advanced users.
Property Pane Configuration
Properties are organized into three groups: Settings, Advanced, and Visibility.
| Property | Group | Type | Required | Description |
|---|---|---|---|---|
title | Settings | Text | No | Web part title displayed above messages. Default value: Important Messages (set by the manifest preconfiguredEntries). Leave empty to hide the title + icon row. |
siteUrl | Settings | Text | No | Site URL for cross-site queries. Leave empty for current site. |
listId | Settings | List Picker | Yes | SharePoint list containing messages. The list ID (GUID) is stored so renames do not break the web part. listName is auto-populated from the picker selection. |
enableContentTargeting | Settings | Toggle | No | Filter messages by SharePoint group membership (TargetAudience field). Default: off. |
maxMessagesToShow | Settings | Slider (1-10) | No | Maximum messages to display at once (default: 1, step: 1). UI label: "Items to Show". |
fixedHeight | Settings | Slider (0-1000, step 50) | No | Fixed container height in pixels. 0 = auto height; any positive value enables vertical scrolling when content overflows. |
description | Advanced | Text (multiline) | No | Optional description for this web part. 3-row multiline input. |
helpUrl | Advanced | Text | No | Optional link to help documentation. |
showInMobileAndEmailView | Visibility | Checkbox | No | Show web part in mobile and email views. Default: on. |
View selection is intentionally not exposed
The web part interface includes
viewName/viewId properties for backward compatibility, but the ViewPicker is not shown in the property pane and the service does not apply view filters today. All filtering happens via the REST query + client-side logic.Required SharePoint List Schema
Create a SharePoint list with these columns:
| Column | Internal Name | Type | Required | Description |
|---|---|---|---|---|
| Title | Title | Single line of text | Yes | Message title |
| Body | Body | Multiple lines (Rich text) | Yes | Message content (HTML) |
| Category | Category | Choice | Yes | Values: Info, Warning, Error, Success |
| Start Date | StartDate | Date and Time | Yes | When message becomes active |
| End Date | EndDate | Date and Time | Yes | When message expires |
| Message Active? | MessageActive | Yes/No | No | Toggle to manually enable/disable message |
| Allow Dismissal? | AllowDismissal | Yes/No | No | Can users dismiss this message? (default: Yes) |
| Target Audience | TargetAudience | Single line of text | No | User group name for content targeting |
Features Checklist
- ✅ Four message categories with distinct styling (Info, Warning, Error, Success — case-insensitive)
- ✅ Date-based activation (StartDate / EndDate) filtered entirely client-side so timezone conversions stay accurate
- ✅ Per-message dismissal control (AllowDismissal field)
- ✅ Per-message activation toggle (MessageActive field)
- ✅ Dismissal state stored in user profile property (FIFO cap of 24) with session-storage fallback
- ✅ Content targeting by user groups (TargetAudience field)
- ✅ Dynamic field name discovery — tolerates renamed columns and SharePoint's
_x003F_encoding of question marks - ✅ Dynamic list picker in property pane (order by title, custom-lists template)
- ✅ Configurable max messages (1-10)
- ✅ Fixed height option (0-1000 px, step 50) with scroll overflow
- ✅ Theme Manager integration (accent color + contrast-aware foreground)
- ✅ HTML sanitization of message body (strips scripts, event handlers, javascript: URIs)
- ✅ Automatic retry on transient errors (up to 2 retries, 1s delay)
- ✅ Actionable empty-state prompts (configuration required / no active messages)
- ✅ Responsive design with Mobile and Email view visibility toggle
- ✅ Cross-site data source support (siteUrl property)
- ✅ License-gated rendering via Bonzai License Manager
- ✅ Keyboard accessible (Escape dismisses, ARIA live region, focusable alert)
Migration from Classic
| Aspect | Classic | Modern |
|---|---|---|
| Technology | XmlWebPart + bonzai.min.js | SPFx + React |
| Message Colors | Brick Theme Editor | CSS Custom Properties via Theme Manager |
| Dismissal Storage | Property bags | User Profile Service property with session fallback |
| Date Filtering | CAML queries | Client-side date comparison (REST query fetches top N by Created desc) |
| List Selection | Manual list name entry | Visual List Picker dropdown |
| View Selection | Manual view name entry | Not available (view filtering not implemented) |