Understanding the SPFx Web Part Lifecycle in Depth

Every SPFx developer has hit a bug that turned out to be code running in the wrong lifecycle method — data fetching in render, DOM manipulation before the component mounts, or properties read before onInit completes.
Understanding exactly when each lifecycle hook fires, and what is available to you at that point, eliminates an entire class of subtle, hard-to-reproduce bugs.
This article walks through every lifecycle method in an SPFx web part, in execution order, with practical guidance on what belongs where.

🗺️ The Lifecycle at a Glance

An SPFx web part goes through four broad stages:

1. Construction — the class is instantiated
2. Initialization — onInit completes async setup before any render
3. Rendering — render produces the DOM output
4. Property changes & teardown — onPropertyPaneFieldChanged, onDispose, etc.

The methods below are listed in the order the framework calls them.

🏗️ constructor()

The constructor runs first. At this point the SharePoint context is not yet available — this.context is undefined.

export default class MyWebPart extends BaseClientSideWebPart<IMyWebPartProps> {
  constructor() {
    super();
    // ✅ Safe: initialise class-level variables
    // ❌ Do NOT call this.context here — it's undefined
  }
}

Rule: Keep the constructor empty or use it only for field initialisation. Never call this.context, this.properties, or any async operation here.

⚙️ onInit(): Promise<void>

onInit is the designated place for all async setup. The framework awaits its return before calling render, so anything you need ready before the first paint goes here.

protected async onInit(): Promise<void> {
  await super.onInit();

  // ✅ Initialise PnPjs with SharePoint context
  const sp = spfi().using(SPFx(this.context));

  // ✅ Fetch configuration data before first render
  this._config = await sp.web.lists.getByTitle('Config').items();

  // ✅ Set up event subscriptions
  this.context.application.navigatedEvent.add(this, this._onNavigated);
}

Common uses for onInit:

• Bootstrapping PnPjs or MSAL
• Fetching configuration or reference data
• Registering event listeners on this.context.application
• Setting up logging / telemetry clients

Rule: Always call await super.onInit() first. Everything that must be ready before the first render belongs here, not in render.

🎨 render(): void

render is called immediately after onInit resolves, and again every time the property pane saves a change. It is synchronous — do not put await calls directly inside it.

public render(): void {
  const element: React.ReactElement<IMyProps> = React.createElement(MyComponent, {
    description: this.properties.description,
    context: this.context,
    onConfigure: this._onConfigure.bind(this)
  });

  ReactDOM.render(element, this.domElement);
}

What belongs in render:

• Creating the root React element
• Passing properties and context down as props
• Rendering a loading skeleton if data is still being fetched in the React component

Rule: Keep render thin. Business logic, data fetching, and side effects belong in onInit or inside your React components via useEffect.

🔄 onPropertyPaneFieldChanged(propertyPath, oldValue, newValue)

Called each time the user changes a field value in the property pane, even before they click Apply.

protected onPropertyPaneFieldChanged(
  propertyPath: string,
  oldValue: unknown,
  newValue: unknown
): void {
  super.onPropertyPaneFieldChanged(propertyPath, oldValue, newValue);

  if (propertyPath === 'listName' && newValue !== oldValue) {
    // Re-fetch data when the target list changes
    this._loadItems(newValue as string).then(() => this.render());
  }
}

Rule: Use this hook to react to individual field changes — for example, populating a dependent dropdown based on the new value. For full re-renders on Apply, render is called automatically — you don't need to trigger it yourself.

💾 onAfterPropertyPaneChangesApplied()

Fires after the user clicks Apply and all pending property changes have been committed to this.properties.

protected onAfterPropertyPaneChangesApplied(): void {
  // All property changes are now committed
  // Safe to persist or log the final values
  console.log('Properties applied:', this.properties);
}

Use this for post-save side effects that should only run on explicit Apply, not on every keystroke.

📐 onBeforeSerialize(): IWebPartData

Called just before the web part's properties are serialised to the page. Lets you transform or trim property values before they are written to storage.

protected onBeforeSerialize(): IWebPartData {
  // Strip runtime-only state before saving
  delete (this.properties as any)._runtimeCache;
  return super.onBeforeSerialize();
}

This is rarely needed, but important when you store ephemeral data on this.properties during runtime that must not be persisted.

🔁 onAfterDeserialize(deserializedObject, dataVersion)

Called after the saved property bag is loaded from storage, giving you a chance to migrate or transform old property shapes.

protected onAfterDeserialize(
  deserializedObject: IMyWebPartProps,
  dataVersion: Version
): IMyWebPartProps {
  // Migrate v1 property shape to v2
  if (dataVersion.compare(new Version(1, 0)) === 0) {
    deserializedObject.listName = deserializedObject['list'] ?? '';
  }
  return deserializedObject;
}

Always use this — rather than onInit — for property schema migrations across data versions.

📏 onDisplayModeChanged(oldDisplayMode)

Fires when the page switches between Edit and Read mode. Use this to swap read-only and interactive variants of your component.

protected onDisplayModeChanged(oldDisplayMode: DisplayMode): void {
  super.onDisplayModeChanged(oldDisplayMode);
  this.render(); // Re-render with the new display mode
}

Pass this.displayMode as a prop to your React component to conditionally show edit controls.

🗑️ onDispose(): void

Called when the web part is removed from the page or the page is closed. Clean up subscriptions, timers, and any external resources here.

protected onDispose(): void {
  // ✅ Remove event listeners
  this.context.application.navigatedEvent.remove(this, this._onNavigated);

  // ✅ Unmount the React tree
  ReactDOM.unmountComponentAtNode(this.domElement);

  super.onDispose();
}

Rule: Always call super.onDispose() at the end. Failing to unmount the React tree here causes memory leaks in long-running SharePoint sessions.

📊 Lifecycle Execution Order — Summary

new MyWebPart()
  └── constructor()
        └── onInit()          ← async setup, awaited by framework
              └── render()    ← first paint
                    ├── [user edits property pane]
                    │     ├── onPropertyPaneFieldChanged()
                    │     └── onAfterPropertyPaneChangesApplied()
                    ├── [page mode changes]
                    │     └── onDisplayModeChanged()
                    ├── [before save]
                    │     └── onBeforeSerialize()
                    └── [web part removed]
                          └── onDispose()

🔬 Observing the Lifecycle Yourself

The companion GitHub sample for this article implements a lifecycle logger web part that logs every hook — including timestamps and the values available at each stage — directly to the browser console.

Clone it, add it to your workbench, open DevTools, and you'll see the exact execution order in your own tenant.

✅ Summary

• constructor — field initialisation only; this.context is not available yet.
• onInit — all async setup: PnPjs bootstrap, config fetch, event subscriptions. Awaited before first render.
• render — thin; create the React element and mount it. No async calls here.
• onPropertyPaneFieldChanged — react to individual field edits, e.g. refresh a dependent dropdown.
• onAfterPropertyPaneChangesApplied — post-save side effects after the user clicks Apply.
• onBeforeSerialize / onAfterDeserialize — transform properties before save or after load.
• onDisplayModeChanged — switch between read and edit variants.
• onDispose — remove listeners, unmount React, release resources.

Getting these boundaries right means fewer mysterious bugs and cleaner, more maintainable web parts.

Happy coding!