Extensions: Code That Wraps the Whole Site

Lesson 6: Extensions — Code That Wraps the Whole Site

Web parts live inside pages. SPFx extensions live around them: code that runs on every page of a site, or that changes how lists behave. If you need a global banner, a custom column, or a toolbar button, an extension is the tool — and it ships in the exact same .sppkg pipeline as web parts.

The three extension types

In other words: application customizers are site-wide by nature; field customizers and command sets are opt-in per list and are usually attached during provisioning (which is why Lesson 2's tools earn their keep).

A real application customizer

Scaffold one with the generator (yo @microsoft/sharepoint → Application Customizer) and you get a class like this — here extended to show a dismissible notice bar in the top placeholder:

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

export interface INoticeBarApplicationCustomizerProperties {
  message: string;   // configurable: set when you register the extension
}

export default class NoticeBarApplicationCustomizer
  extends BaseApplicationCustomizer<INoticeBarApplicationCustomizerProperties> {

  public onInit(): Promise<void> {
    Log.info('NoticeBar', 'initialized');
    // Placeholders appear async — render when the top region is ready
    this.context.placeholderProvider.changedEvent.add(this, this._render);
    this._render();
    return Promise.resolve();
  }

  private _render(): void {
    const placeholder = this.context.placeholderProvider
      .tryCreateContent(PlaceholderName.Top, { onDispose: null });

    if (!placeholder) { return; }   // top slot already taken by another extension

    const message = this.properties.message || 'Default notice';
    placeholder.domElement.innerHTML = `
      <div style="background:#fde7e9;color:#a4262c;padding:8px 16px;
                  font-family:Segoe UI,sans-serif;font-size:14px;text-align:center">
        ${message}
      </div>`;
  }
}

What to notice

• onInit() is the extension lifecycle hook — the right place to subscribe and render once.
• placeholderProvider exposes the page's injection slots (PlaceholderName.Top / .Bottom). Only one extension can own a slot; tryCreateContent returns undefined if it's taken — always handle that.
• Properties travel with registration: unlike web parts, an app customizer's message isn't set by a property pane — you provide it when registering/installing the extension (via the component's properties during provisioning). The code must default gracefully.

Further Reading

• Overview of SPFx extensions (Microsoft Learn)