Creating a SharePoint Framework (SPFx) Extension with a Custom Top Navigation Menu

Introduction

In this guide, we will create a SharePoint Framework (SPFx) Application Customizer that adds a custom top navigation menu to SharePoint Online pages. This solution leverages the placeholder framework provided by SPFx, ensuring seamless integration within SharePoint’s UI.

This approach follows Microsoft’s best practices, as outlined in the official documentation: Using Page Placeholders with SPFx Extensions.

Prerequisites

Before starting, ensure you have the following installed:

• Node.js (LTS version)
• Yeoman and the SharePoint Generator: npm install -g yo @microsoft/generator-sharepoint
• Gulp CLI: npm install -g gulp-cli
• A SharePoint Online environment to deploy and test the extension.

Step 1: Generate an SPFx Extension Project

1. Create a new folder for the solution and navigate to it: mkdir spfx-top-menu && cd spfx-top-menu
2. Run the SharePoint generator: yo @microsoft/sharepoint
3. Provide the following responses to the generator prompts:
   • Solution Name? → spfx-top-menu
   • Target environment? → SharePoint Online only (latest)
   • Type of component? → Extension
   • Type of extension? → Application Customizer
   • Name? → TopMenu
   • Framework? → No JavaScript framework

Step 2: Implement the Custom Top Menu

Open the file src/extensions/topMenu/TopMenuApplicationCustomizer.ts and replace its content with the following:

import { override } from '@microsoft/decorators';
import { Log } from '@microsoft/sp-core-library';
import {
  BaseApplicationCustomizer,
  PlaceholderContent,
  PlaceholderName
} from '@microsoft/sp-application-base';

const LOG_SOURCE: string = 'TopMenuApplicationCustomizer';

export interface ITopMenuApplicationCustomizerProperties {
  menuItems: string;
}

export default class TopMenuApplicationCustomizer
  extends BaseApplicationCustomizer<ITopMenuApplicationCustomizerProperties> {
  
  private _topPlaceholder: PlaceholderContent | undefined;

  @override
  public onInit(): Promise<void> {
    Log.info(LOG_SOURCE, `Initialized ${LOG_SOURCE}`);
    
    this.context.placeholderProvider.changedEvent.add(this, this.renderTopMenu);
    this.renderTopMenu();
    
    return Promise.resolve();
  }

  private renderTopMenu(): void {
    if (!this._topPlaceholder) {
      this._topPlaceholder = this.context.placeholderProvider.tryCreateContent(
        PlaceholderName.Top,
        { onDispose: () => console.log("Disposed top placeholder") }
      );
    }

    if (!this._topPlaceholder || !this._topPlaceholder.domElement) {
      console.error("Top placeholder not available!");
      return;
    }

    this._topPlaceholder.domElement.innerHTML = `
      <style>
        .custom-top-menu {
          background-color: #0078d4;
          color: white;
          padding: 10px;
          text-align: center;
          font-size: 16px;
        }
        .custom-top-menu a {
          color: white;
          margin: 0 15px;
          text-decoration: none;
          font-weight: bold;
        }
      </style>
      <div class="custom-top-menu">
        <a href="/">Home</a>
        <a href="/sites/mysite">My Site</a>
        <a href="/_layouts/15/viewlsts.aspx">Lists</a>
      </div>
    `;
  }
}

Step 3: Update config.json

Modify the configuration file ./config/config.json to include properties:

"TopMenuApplicationCustomizer": {
  "properties": {
    "menuItems": "Home,My Site,Lists"
  }
}

Step 4: Package and Deploy the Extension

1. Compile the project: gulp build
2. Bundle the solution for deployment: gulp bundle --ship
3. Create a SharePoint package: gulp package-solution --ship
4. Upload the package (.sppkg file located in sharepoint/solution/) to the SharePoint App Catalog.
5. Deploy and activate the extension on a SharePoint site.

Conclusion

By following this guide, you have successfully created an SPFx Application Customizer that injects a top navigation menu into SharePoint Online pages using the placeholder framework. This method ensures better maintainability and compatibility with SharePoint UI updates.

For additional details, refer to the official Microsoft documentation: Using Page Placeholders with SPFx Extensions.