The Alert Banner SPFx Extension is a custom SharePoint Framework (SPFx) extension designed to display Announcements and Alert notifications prominently as a Banner on Modern SharePoint sites. These alerts are dynamically retrieved from a SharePoint list using the Microsoft Graph API, ensuring users receive important updates and information seamlessly integrated with Microsoft 365 services.

Collapsed Alert Banner

Alert Banner with Settings Button

Alert Templates Selection

Choose from pre-configured templates to quickly create alerts.

Manage Alerts List View

View and manage all your alerts in one place.

Alert Details (Expanded)

View detailed information for each alert including scheduling and targeting.

Alert Types Management

Create and customize alert types with custom icons, colors, and styling.

Feature Settings

Configure user targeting, browser notifications, and carousel settings.

Multi-Language Support Setup

Configure multi-language support with automatic SharePoint list field management.

Language Selection

Choose from 8 built-in languages or add custom languages.

Create Alert with Live Preview

See how your alert will look as you create it.

Description Editor

Rich text editor with formatting options and emoji support.

Alert Configuration

Configure alert type, priority, notification settings, and more.

Target Sites Selection

Choose which sites should display the alert (current site, hub site, or home site).

Scheduling Options

Set start and end dates for time-based alert display.

Multi-Language Content Editor (English)

Create content in English and other languages.

Multi-Language Content Editor (French)

Switch between languages to provide translations.

Multi-Language Content Summary

View completion status for all configured languages.

Manage Alerts with Filters

Filter and search alerts by content type, priority, alert type, status, language, and more.

Alert banners are frequently requested by organizations such as IT departments but are not readily available out-of-the-box. This extension aims to provide a flexible and reusable alert system that any organization can deploy with ease.

Additionally, this project serves as an opportunity to refresh and enhance coding skills within the SPFx ecosystem.

• SharePoint Framework
• Microsoft 365 tenant

Get your own free development tenant by subscribing to the Microsoft 365 developer program.

• Node.js (v22.14.0 or later)
• React 17
• SPFx (v1.21.1 or later)
• A SharePoint Online site collection
• Appropriate permissions to access and configure the tenant App Catalog

THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.

• Clone this repository.
• Navigate to the solution folder.
• In the command line, run:
  • npm install
  • ./buildProject.cmd
  • Deploy to app catalog

Additional steps may be required depending on your environment configuration.

This SPFx extension offers the following capabilities:

• Fetch Alerts: Retrieves alerts from a designated SharePoint list using the Microsoft Graph API.
• Display Alerts: Show alerts prominently in the banner of Modern SharePoint pages, with detailed content displayed directly within the expanded banner.
• Dynamic Alert Type Configuration: Configure alert types dynamically using a JSON property, allowing easy customization and scalability.
• User Interaction Handling: Allows users to dismiss alerts, with the option to prevent dismissed alerts from reappearing.
• Performance Optimization: Utilizes local storage for caching alerts, improving performance.
• Multi-Site Support: Support for Root, Local, and Hub sites.
• Alert Prioritization: Categorize alerts as Low, Medium, High, or Critical with visual differentiation.
• Simplified User Targeting: Target alerts using SharePoint People/Groups picker - select specific users or groups, or leave empty for everyone to see.
• Notification System: Send browser notifications for critical and high-priority alerts.
• HTML Content Support: Rich text descriptions with HTML formatting, including images, links, and styled content.
• Action Links: Optional action links with customizable descriptions for enhanced user engagement.
• Advanced Multi-Language System: Dynamic language targeting with intelligent fallback logic, language-aware audience filtering, and automatic user language detection from SharePoint/browser settings.
• Dynamic Language Management: Self-updating SharePoint choice fields that automatically add/remove language options based on administrator configuration.
• Multi-Language Content Editor: Comprehensive interface for creating and managing alert content across multiple languages with validation and status tracking.
• Language-Aware Audience Targeting: Users automatically see alerts in their preferred language (French users see French, German users see German) with smart fallback to available languages.
• Hierarchical Alert System: Intelligent alert distribution based on SharePoint site hierarchy (Home Site → Hub Site → Current Site).
• Automatic List Management: Smart detection and one-click creation of alert lists across site hierarchy.
• Site Context Awareness: Automatic detection of Home Sites, Hub Sites, and current site relationships.

The Alert Banner extension now includes comprehensive multi-language support with the following features:

• English (en-us) - English (Default)
• French (fr-fr) - Français
• German (de-de) - Deutsch
• Spanish (es-es) - Español
• Swedish (sv-se) - Svenska
• Finnish (fi-fi) - Suomi
• Danish (da-dk) - Dansk
• Norwegian (nb-no) - Norsk bokmål

• Automatic Detection: Detects user's language from SharePoint context or browser settings
• Manual Selection: Users can manually change language through the language selector in settings
• Persistent Preferences: Language choice is stored in browser local storage
• Fallback Support: Falls back to English if requested language is not available
• Date/Time Localization: Automatically formats dates and times according to selected locale
• String Interpolation: Dynamic content with parameter substitution
• RTL Ready: Framework supports right-to-left languages (when needed)

Access the language selector through the Alert Settings dialog (available when in edit mode). The system will automatically detect the user's preferred language based on their SharePoint/browser settings, but users can manually override this selection.

For detailed information about localization features, development guidelines, and adding new languages, see LOCALIZATION.md.

The Alert Banner extension uses an intelligent hierarchical system to display alerts based on SharePoint site relationships:

• Home Site Alerts: Displayed on ALL sites across the tenant - perfect for organization-wide announcements
• Hub Site Alerts: Displayed on the hub site and all sites connected to that hub - ideal for department or division updates
• Current Site Alerts: Displayed only on the specific site - best for site-specific notifications

The extension automatically detects:

• Your organization's Home Site (if configured)
• Hub Site connections for the current site
• Site relationships and permissions
• Existing alert lists across the hierarchy

The extension provides intelligent list management:

• Automatic Detection: Checks if alert lists exist on relevant sites
• One-Click Creation: Create missing alert lists directly from settings
• Permission Validation: Shows what you can access and create
• Visual Status Indicators: Clear icons show list availability and status

The Alert Banner extension now supports creating content in multiple languages, allowing organizations to communicate effectively with diverse audiences.

1. Access the Editor: When creating or editing alerts through the Settings interface, you'll see a multi-language content section
2. Select Languages: Use the language tabs to switch between different language versions of your content
3. Add Content: Fill in the Title, Description, and Link Description for each language
4. Language Management: Add custom languages using the "Add Language" button

1. Primary Language: Start by creating content in your primary language (typically English)
2. Add Translations: Use the language tabs to switch to other languages and provide translations
3. Content Validation: The system shows a summary of which languages have content
4. Publish: Save the alert - users will automatically see content in their preferred language

Beyond the 8 built-in languages, administrators can add custom languages:

1. Add Language: Click "Add Language" in the multi-language editor
2. Language Details: Provide language code (e.g., 'it-it'), name, and native name
3. Quick Setup: Choose from suggested languages or manually configure
4. Automatic Columns: The system automatically creates SharePoint list columns for the new language

The extension uses an intelligent fallback system:

• Primary: Shows content in user's preferred language
• Secondary: Falls back to English if preferred language content is missing
• Tertiary: Uses default Title/Description fields as final fallback

• Consistent Messaging: Ensure translations convey the same meaning and urgency
• Cultural Adaptation: Consider cultural context, not just literal translation
• Testing: Preview alerts in different languages before publishing
• Maintenance: Keep translations updated when primary content changes

The Alert Banner extension implements a sophisticated three-tier alert system that follows SharePoint's natural site hierarchy:

1. Automatic Detection: The extension scans your SharePoint environment to identify:

   • Home Site (if configured at tenant level)
   • Hub Site connections for the current site
   • Current site context and permissions

2. Intelligent Querying: Only queries sites that:

   • Have alert lists created
   • User has permission to access
   • Are relevant to the current site context

3. Hierarchical Display: Alerts are displayed in priority order:

   • Home Site alerts (highest priority - shown everywhere)
   • Hub Site alerts (medium priority - shown on hub and connected sites)
   • Site alerts (local priority - shown on specific site only)

The Settings dialog includes a comprehensive List Management section that provides:

• Site Hierarchy Visualization: See your Home Site, Hub Site, and Current Site relationships
• List Status Indicators: Visual status for each site's alert list (✅ Available, ⚠️ Limited Access, ❌ Missing, ➕ Can Create)
• One-Click List Creation: Create missing alert lists with full field schema
• Permission Validation: Clear indication of what actions are available
• Real-Time Updates: Status updates immediately when lists are created

• Use for critical, tenant-wide communications
• Keep content concise and universally relevant
• Consider multi-language content for global organizations
• Use high priority levels sparingly

• Focus on department or division-specific content
• Leverage user targeting for role-specific messages
• Coordinate with hub site owners for content strategy
• Use medium priority for most communications

• Perfect for team notifications and project updates
• Use lower priority levels for routine communications
• Use HTML content in descriptions for rich formatting
• Target specific user groups as needed

The Alert Banner extension automatically creates and manages SharePoint lists with the following fields:

Multi-language support is managed through a simple choice field approach:

• TargetLanguage Choice Field: Contains language options (all, en-us, fr-fr, de-de, etc.)
• Language Group Field: Groups related language variants of the same content
• Content Approach: Each alert targets a specific language using the TargetLanguage choice field
• Dynamic Management: The Language Management interface automatically adds new language options to the TargetLanguage choice field

How it works:

1. Create separate alert items for each language version
2. Use the same LanguageGroup value to link related language variants
3. Set TargetLanguage to specify which users should see each version
4. Users automatically see the version that matches their language preference

Note: The extension automatically manages the TargetLanguage choice field options when administrators add new languages through the interface.

• AlertType: Create choice values matching your alert type configurations (Info, Warning, Maintenance, Interruption, etc.)
• Priority: Create these choice values: Low, Medium, High, Critical
• NotificationType: Create these choice values: none, browser, email, both

• Banner Integration: Alerts display prominently in the SharePoint page banner
• Visual Priority Indicators: Color-coded styling based on alert priority levels
• Expandable Content: Click to expand/collapse detailed alert information
• Responsive Design: Adapts seamlessly to desktop, tablet, and mobile devices
• Accessibility First: Full keyboard navigation and screen reader support

• Comprehensive Settings Panel: All configuration options accessible through intuitive interface
• CRUD Operations: Create, read, update, and delete alerts with full form validation
• Multi-Language Content Editor: Tabbed interface for managing content across multiple languages
• List Management: One-click creation of alert lists across site hierarchy
• Language Management: Dynamic addition of new languages with automatic field creation

Alert types can be customized dynamically using a JSON configuration property. This allows administrators to add, modify, or remove alert types without altering the codebase. The JSON structure defines the appearance and behavior of each alert type, including icons, colors, and additional styles.

Example JSON Structure:

[
  {
    "name": "Info",
    "iconName": "Info12",
    "backgroundColor": "#389899",
    "textColor": "#ffffff",
    "additionalStyles": "",
    "priorityStyles": {
      "critical": "border: 2px solid #E81123;",
      "high": "border: 1px solid #EA4300;",
      "medium": "",
      "low": ""
    }
  },
  {
    "name": "Warning",
    "iconName": "ShieldAlert",
    "backgroundColor": "#f1c40f",
    "textColor": "#ffffff",
    "additionalStyles": ""
  },
  {
    "name": "Maintenance",
    "iconName": "CRMServices",
    "backgroundColor": "#afd6d6",
    "textColor": "#ffffff",
    "additionalStyles": ""
  },
  {
    "name": "Interruption",
    "iconName": "IncidentTriangle",
    "backgroundColor": "#c54644",
    "textColor": "#ffffff",
    "additionalStyles": ""
  }
]

Version 3.0 features simplified user targeting using SharePoint's built-in People and Groups picker:

• Simple Selection: Use the intuitive SharePoint People/Groups field to select target audiences
• Individual Users: Select specific users by name or email
• SharePoint Groups: Target entire SharePoint groups or security groups
• Universal Access: Leave the field empty for alerts visible to everyone
• No JSON Required: Eliminated complex JSON-based targeting rules for ease of use

Alerts support rich HTML content directly in the Description field:

• Rich Text Editor: Built-in SharePoint rich text editor with formatting options
• HTML Support: Full HTML content including images, links, and styling
• Media Integration: Embed images and links directly in the description
• Responsive Design: Content automatically adapts to different screen sizes
• Content Sanitization: Built-in security measures prevent malicious content

The Alert Banner is designed with accessibility in mind:

• Keyboard Navigation: Full keyboard support for all interactive elements.
• Screen Reader Support: Proper ARIA attributes for better screen reader integration.
• Focus Management: Managed focus trap in dialogs to improve keyboard accessibility.
• Color Contrast: Meets WCAG 2.1 AA standards for color contrast.
• Text Scaling: Supports browser text scaling for vision impairments.
• RTL Language Support: Right-to-left language layout support for global accessibility.

The Alert Banner is optimized for performance:

• Efficient Rendering: Uses React memo and callback optimizations to reduce render cycles.

• Caching Strategy: Implements local and session storage for efficient alert management.

• Component Splitting: Modular design allows for better code splitting.

• CSS Optimization: Carefully organized SCSS with variables for minimal CSS output.

1. SharePoint Administrator Access: Required to deploy to the tenant App Catalog
2. Site Collection Administrator: Needed for site-specific configurations
3. Development Environment: Node.js, SPFx CLI, and Visual Studio Code (recommended)

# Clone the repository
git clone https://github.com/NicolasKheirallah/AlertBanner.git
cd AlertBanner

# Install dependencies
npm install

# Build the solution
npm run build

# Bundle and package for production
npm run bundle -- --production
npm run package-solution -- --production

1. Navigate to your SharePoint tenant App Catalog
2. Upload the .sppkg file from the /sharepoint/solution/ folder
3. When prompted, check "Make this solution available to all sites in the organization"
4. Click "Deploy"

The extension can be deployed in three ways:

Option A: Tenant-wide Deployment (Recommended)

1. Go to SharePoint Admin Center
2. Navigate to "Advanced" > "Extensions"
3. Add the Alert Banner extension with appropriate scoping

Option B: Site Collection Feature

1. Go to Site Settings > Site Collection Features
2. Activate "Alert Banner Application Customizer"

Option C: Manual Property Configuration Add the following to the site's User Custom Actions via PowerShell/CLI for Microsoft 365:

m365 spo customaction add --webUrl "https://yourtenant.sharepoint.com/sites/yoursite" --location "ClientSideExtension.ApplicationCustomizer" --name "AlertBannerApplicationCustomizer" --clientSideComponentId "12345678-1234-1234-1234-123456789012"

1. Automatic Site Detection: The extension detects your site hierarchy (Home Site, Hub Site, Current Site)
2. List Status Check: Verifies which sites have alert lists and your permissions
3. Settings Access: Open the Settings dialog in edit mode to manage the extension
4. List Creation: Use the integrated List Management to create missing alert lists with one click

Use the field configuration table in the Managing Alerts section to set up your SharePoint list fields correctly.

• Read permissions: Required for viewing alerts
• Contribute permissions: Needed for dismissing alerts
• Design/Full Control: Required for configuring alert settings

1. Clear browser cache: Hard refresh (Ctrl+F5) or clear SharePoint cache
2. Check deployment status: Verify the .sppkg file was successfully deployed in App Catalog
3. Verify feature activation: Ensure the site collection feature is activated
4. Check permissions: User needs at least read access to the site

1. Site Hierarchy: Check if alerts exist at the appropriate level (Home/Hub/Current site)
2. List Management: Use Settings → List Management to verify alert lists exist
3. List fields: Ensure all required fields exist with correct types
4. Alert dates: Check ScheduledStart and ScheduledEnd fields
5. User targeting: Verify TargetUsers field contains appropriate users/groups
6. Hub connections: Verify site is connected to expected hub (if applicable)
7. Home site: Confirm organization has a configured Home Site (for tenant-wide alerts)
8. Browser console: Check for JavaScript errors or network issues

1. Missing translations: Check browser console for warnings about missing string keys
2. Language not switching: Clear browser local storage for the site
3. Date format issues: Verify browser locale settings
4. Text overflow: Some languages require more space - check responsive layout

1. Large alert lists: Consider archiving old alerts or implementing pagination
2. HTML content: Optimize embedded images and media in descriptions
3. Network latency: Check SharePoint service health and connectivity

1. Site Hierarchy Check: Use Settings → List Management to view detected site hierarchy
2. List Status Verification: Check which sites have alert lists and permission status
3. Enable debug mode: Add #debug=1 to the URL to see additional console logging
4. Check Network tab: Monitor API calls to SharePoint in browser developer tools
5. Hub Site Verification: Confirm expected hub site connections in Site Settings
6. Home Site Configuration: Verify Home Site is configured at tenant level
7. Inspect local storage: Look for cached data and language preferences
8. Review SharePoint logs: Check tenant admin center for any error reports

• GitHub Issues: Report bugs at https://github.com/NicolasKheirallah/AlertBanner/issues
• Documentation: Refer to LOCALIZATION.md for language-specific help
• Community: SharePoint development community forums and Microsoft Tech Community

• Animations and transitions are limited for cross-browser compatibility
• Outlook web integration is in development for a future release
• Custom notification sounds are not currently supported

• Getting started with SharePoint Framework
• Building for Microsoft Teams
• Use Microsoft Graph in your solution
• Publish SharePoint Framework applications to the Marketplace
• Microsoft 365 Patterns and Practices - Guidance, tooling, samples, and open-source controls for your Microsoft 365 development.
• FluentUI React Components

This extension showcases:

• Integration of the Microsoft Graph API within SPFx extensions for efficient data retrieval.
• Hierarchical Site Architecture: Intelligent detection and utilization of SharePoint's Home Site, Hub Site, and site relationships.
• Multi-Site Alert Management: Sophisticated querying across site hierarchy with permission-aware access control.
• Dynamic Configuration Management: Utilizing JSON properties to configure alert types, enhancing flexibility and maintainability.
• Automatic List Detection and Creation: Smart discovery of existing alert lists with one-click creation of missing infrastructure.
• Site Context Awareness: Comprehensive service for detecting and managing SharePoint site relationships and permissions.
• Direct content display within the banner of Modern SharePoint pages to provide a consistent and visible alerting mechanism.
• Efficient State Management and Caching using local and session storage to optimize performance and reduce redundant data fetching.
• Multi-Language Content Management: Column-based approach for creating and managing content in multiple languages.
• Responsive Design and User Interaction Handling to ensure alerts are accessible and user-friendly across various devices and screen sizes.
• Simplified User Targeting using SharePoint People/Groups picker integration.
• HTML Content Rendering with built-in sanitization and security measures.
• Modern FluentUI Implementation with proper component hierarchy and styling patterns.
• Accessibility-First Design ensuring usability for all users regardless of ability.