When developers start with the SharePoint Framework, the most common entry point is building web parts. Web parts are powerful, modular, and ideal for isolated UI components.

Understanding SPFx Application Customizer in SharePoint Online

Extending SharePoint Beyond Web Parts

When developers start with the SharePoint Framework, the most common entry point is building web parts. Web parts are powerful, modular, and ideal for isolated UI components.

But SharePoint has another layer of extensibility.

A layer that allows you to inject functionality directly into the page lifecycle.

This is where SPFx Extensions become critical.

Among them, the Application Customizer is one of the most important.

It allows developers to:

• inject UI into page placeholders
• execute scripts globally
• manipulate navigation
• create banners
• implement telemetry
• build corporate headers/footers
• create redirect engines for migrated sites

For enterprise SharePoint development, this is one of the most valuable tools.

What is an Application Customizer?

An Application Customizer is an SPFx Extension that runs when a SharePoint page loads.

Unlike a web part:

Think like this:

Web Parts = components
Application Customizers = page-level behaviors

Official Microsoft documentation:

SPFx Extensions Overview

Types of SPFx Extensions

Microsoft provides three extension models:

1. Application Customizer

Page-level customization.

Examples:

• top banners
• bottom notifications
• global scripts
• redirects

2. Field Customizer

Used inside list views.

Examples:

• custom column rendering
• badges
• icons
• conditional UI

3. ListView Command Set

Adds buttons to list command bars.

Examples:

• export actions
• integrations
• custom workflows

Why Application Customizer matters in real projects

In many enterprise scenarios, you need behavior across the entire site.

Examples:

Legacy site redirect

Migration:

/teams/hr
→ /sites/hr

Old bookmarks still exist.

Instead of breaking access:

if(window.location.pathname.includes("/teams/hr")){
   window.location.href = "/sites/hr";
}

Solved.

Global corporate alert

Example:

System maintenance this weekend.

Inject into top placeholder.

Custom footer

Add:

• helpdesk links
• policies
• legal disclaimers

Breadcrumb enhancement

Create dynamic navigation.

Analytics tracking

Send page access data to:

• Microsoft Power BI
• Azure Application Insights
• Microsoft Graph

Application Customizer lifecycle

The most important lifecycle method:

public onInit(): Promise<void>

This runs when the page initializes.

Typical use:

• load settings
• detect URL
• register placeholders
• inject UI

Page placeholders

This is the core concept.

SharePoint provides injectable zones.

Main placeholders:

Top

Before page content.

Example:

[Top Placeholder]
------------------
Page content

Bottom

After page content.

Example:

Page content
------------------
[Bottom Placeholder]

Official Microsoft docs:

Use Page Placeholders

Creating your first Application Customizer

Microsoft official walkthrough:

Build First Application Customizer

Command:

yo @microsoft/sharepoint

Choose:

Extension
Application Customizer

Basic implementation

MyCustomizer.ts

import {
  BaseApplicationCustomizer
} from '@microsoft/sp-application-base';
export interface IMyCustomizerProperties {
  message: string;
}
export default class MyCustomizer
extends BaseApplicationCustomizer<IMyCustomizerProperties> {
  public onInit(): Promise<void> {
    console.log("Application Customizer initialized");
    return Promise.resolve();
  }
}

Using placeholders

Injecting into Top placeholder:

import {
  PlaceholderContent,
  PlaceholderName
} from '@microsoft/sp-application-base';
private _topPlaceholder: PlaceholderContent | undefined;
public onInit(): Promise<void> {
  this._topPlaceholder =
    this.context.placeholderProvider.tryCreateContent(
      PlaceholderName.Top
    );
  if (this._topPlaceholder) {
    this._topPlaceholder.domElement.innerHTML =
      `<div>Corporate Banner</div>`;
  }
  return Promise.resolve();
}

This creates a live banner.

Deploying the extension

Application Customizers are usually deployed:

Site scoped

Only one site.

Site Collection scoped

Whole collection.

Tenant-wide

Entire tenant.

Official:

Tenant Wide Deployment

Important: Does it work in subsites?

Yes.

This is a common question.

Application Customizer works in:

✅ Root sites
✅ Site collections
✅ Subsites

But there’s a rule:

The UserCustomAction must exist in that web.

This means:

If your subsite does not inherit or receive the registration, it will not run.

Official:

Tenant Wide Deployment Extensions

Important for migration projects

This is especially powerful for SharePoint migrations.

Example:

Old structure:

/teams/finance/reports

New structure:

/sites/finance/reports

Instead of fixing thousands of old links manually:

Use an Application Customizer.

Pseudo logic:

const redirects = {
 "/teams/finance": "/sites/finance",
 "/teams/hr": "/sites/hr"
};

Detect and redirect.

This becomes an atomic migration support app.

Perfect for enterprise modernization.

Best practices

Keep it lightweight

It loads on every page.

Heavy logic hurts performance.

Use React only if needed

Simple DOM injection may be enough.

Always dispose placeholders

Use:

onDispose()

To avoid memory leaks.

Avoid unnecessary API calls

Cache whenever possible.

Use centralized config

Store redirects in:

• SharePoint List
• Tenant Property
• JSON file

Better governance.

Final thoughts

Application Customizer is one of the most underestimated parts of SPFx.

Most developers stay inside web parts.

But real enterprise solutions often need:

• page-level behavior
• navigation control
• migration support
• global UI injection
• compliance banners
• analytics

This is where Application Customizer shines.

In a SharePoint architecture mindset:

Web Parts solve isolated problems.

Application Customizers solve environmental problems.

And in corporate SharePoint, environmental problems are everywhere.

That makes this one of the most strategic SPFx tools you can master.