That’s exactly what environment variables fix. And once you understand how they work in SPFx, you’ll wonder how you ever managed without them.

Let me walk you through everything, from the simplest one-liner fix to more advanced patterns for build-time config injection, so you can pick the approach that fits your project.

Let me explain how to use SharePoint Framework (SPFx) environment variables.

What Are SPFx Environment Variables, Really?

Think of environment variables as settings that live outside your code. Instead of hardcoding https://mytenant.sharepoint.com directly in a config file or TypeScript file, you store it in your operating system (or a .env file), and your project just reads it from there.

This is incredibly useful when:

• You work in a team where everyone has a different SharePoint tenant URL
• You deploy to multiple environments — dev, staging, production
• You don’t want API keys or secrets accidentally committed to your Git repo
• You want your CI/CD pipeline to inject the right values at build time

If you want to learn SPFx development, check out our SPFx training course.

Method 1: The SPFX_SERVE_TENANT_DOMAIN Built-In Variable

This is the easiest method and requires zero npm packages. Microsoft built it directly into the SPFx toolchain.

Here’s how it works: when you run gulp serve or heft start, the build system looks for an OS environment variable called SPFX_SERVE_TENANT_DOMAIN and swaps out the {tenantDomain} placeholder in your serve.json automatically.

Step 1 — Update your serve.json

Open config/serve.json and use the placeholder instead of a hardcoded URL:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "initialPage": "https://{tenantDomain}/sites/mysite/_layouts/workbench.aspx"
}

Notice {tenantDomain} — The toolchain will replace this at runtime with the value of your OS environment variable.

Step 2 — Set the environment variable

On Windows (PowerShell) — temporary for this session only:

$env:SPFX_SERVE_TENANT_DOMAIN = "contoso.sharepoint.com"

To make it permanent (so you don’t have to set it every time):

[System.Environment]::SetEnvironmentVariable("SPFX_SERVE_TENANT_DOMAIN", "contoso.sharepoint.com", "User")

Here, update ‘contoso‘ with your tenant domain name.

After some time, reopen your SPFx web part Terminal pane, and check whether the variable contains a value or not with this command echo $env:SPFX_SERVE_TENANT_DOMAIN

On macOS / Linux:

export SPFX_SERVE_TENANT_DOMAIN="contoso.sharepoint.com"

To persist it, add that line to your ~/.bashrc or ~/.zshrc.

Step 3 — Run gulp serve as usual

That’s it. The build toolchain replaces {tenantDomain} on the fly before opening the browser. No code changes, no config file edits per developer.

NOTE: If you are using SPFx solutions with gulp packages, then run the gulp serve command to test. In case you are on SPFx version 1.22.*, with the Heft-based tool chain, run the Heft start command.

In the image below, you can see that the initialPage URL in serve.json has a placeholder called {tenantDomain}. Now, instead of hardcoding our SharePoint tenant domain directly in this URL, we created an environment variable called SPFX_SERVE_TENANT_DOMAIN and stored our tenant domain value in it.

So now when we run the heft start command, SPFx is smart enough to automatically read that environment variable and replace the {tenantDomain} placeholder with our actual tenant domain in the URL.

Why I like this method: It’s the simplest possible solution for the most common pain point. It works out of the box with every SPFx version and requires no extra packages. The downside is it only handles the tenant domain/URL for serve.json — it doesn’t help with injecting variables into your TypeScript code.

Method 2: OS Environment Variables in PowerShell (Quick and Practical)

Sometimes you just need to pass a value temporarily before running a command. PowerShell makes this very easy.

Temporary (session only):

$env:SPFX_API_KEY = "my-api-key-12345"
gulp serve

This variable exists only until you close the terminal window.

Permanent (User scope):

[System.Environment]::SetEnvironmentVariable("SPFX_API_KEY", "my-api-key-12345", "User")

Permanent (Machine scope — needs admin):

[System.Environment]::SetEnvironmentVariable("SPFX_API_KEY", "my-api-key-12345", "Machine")

Check if it’s set:

$env:SPFX_API_KEY

Remove it:

# From session only
Remove-Item Env:\SPFX_API_KEY

# Permanently (User scope)
[System.Environment]::SetEnvironmentVariable("SPFX_API_KEY", $null, "User")

In the image above, you can see I removed the current session variable. When I check back, does it still contain a value? It shows empty.

This method is great for quick local testing. But if you’re working in a team, it gets tedious; every developer has to remember to set all the right variables manually. That’s where .env files come in.

Method 3: Using .env Files with dotenv (Recommended for Teams)

This is my favorite approach for team projects with the gulp-based toolchain (SPFx versions before 1.22). You define all your variables in a .env file, exclude them from version control, and dynamically inject them into Webpack during the build process.

Step 1 —  Install Required Packages

Install dotenv to read the files, and cross-env to easily switch environments across Windows, Mac, and CI/CD pipelines.

npm install dotenv cross-env --save-dev

Step 2 — Create your Environment Files

Create a folder named env at the root of your project, and create a file named dev.env (for local development) and prod.env (for production).

# env/dev.env
SPFX_API_BASE_URL=https://dev-api.contoso.com
SPFX_APP_INSIGHTS_KEY=dev-abc123-xyz
SPFX_ENVIRONMENT=development

Step 3 — Add environment files to .gitignore

This is critical. You never want to commit API keys or production secrets to your repository.

# .gitignore
env/*.env
!env/sample.env

(Tip: It is good practice to commit a sample.env with dummy values so new developers know what variables they need to configure).

Step 4 — Update gulpfile.js for Dynamic Injection

Instead of hardcoding every variable, we can configure Webpack to automatically find and inject any variable that starts with SPFX_. Replace your gulpfile.js with this:

'use strict';

const gulp = require('gulp');
const build = require('@microsoft/sp-build-web');
const webpack = require('webpack');
const dotenv = require('dotenv');
const fs = require('fs');
const path = require('path');

// 1. Determine the environment (default to 'dev')
const environment = process.env.NODE_ENV || 'dev';
const envPath = path.resolve(__dirname, `./env/${environment}.env`);

// 2. Load the file if it exists
let envConfig = {};
if (fs.existsSync(envPath)) {
  envConfig = dotenv.config({ path: envPath }).parsed || {};
} else {
  console.warn(`[!] Warning: ${envPath} not found. Proceeding without env injection.`);
}

// 3. Merge into Webpack configuration
build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfig) => {
    const definitions = {};

    Object.keys(envConfig).forEach((key) => {
      if (key.startsWith('SPFX_')) {
        definitions[`process.env.${key}`] = JSON.stringify(envConfig[key]);
      }
    });

    generatedConfig.plugins.push(new webpack.DefinePlugin(definitions));
    return generatedConfig;
  }
});

// 4. Force task registration (Fixes "Task never defined" error)
let getTasks = build.rig.getTasks;
build.rig.getTasks = function () {
  let result = getTasks.call(build.rig);
  // Ensure serve is properly mapped
  result.set('serve', result.get('serve-deprecated') || result.get('serve'));
  return result;
};

// 5. Initialize build
build.initialize(gulp);

Step 5 — Add TypeScript Typings (Crucial for SPFx)

To prevent TypeScript from complaining that process.env is undefined, create or update a global.d.ts file inside your src folder:

// src/global.d.ts
declare interface NodeJS {
  env: {
    NODE_ENV: 'dev' | 'prod';
    SPFX_API_BASE_URL: string;
    SPFX_APP_INSIGHTS_KEY: string;
    SPFX_ENVIRONMENT: string;
    [key: string]: string | undefined;
  };
}
declare var process: NodeJS;

Step 6 — Use Variables in your TypeScript/React Code

Because of the typings in Step 5, you no longer need as string. You get full IntelliSense autocomplete natively in VS Code.

import * as React from 'react';
import styles from './Listitems.module.scss';
import type { IListitemsProps } from './IListitemsProps';
import { escape } from '@microsoft/sp-lodash-subset';

export default class Listitems extends React.Component<IListitemsProps> {
  public render(): React.ReactElement<IListitemsProps> {
    const {
      description,
      isDarkTheme,
      environmentMessage,
      hasTeamsContext,
      userDisplayName
    } = this.props;

    return (
      <section className={`${styles.listitems} ${hasTeamsContext ? styles.teams : ''}`}>
        <div className={styles.welcome}>
          <img alt="" src={isDarkTheme ? require('../assets/welcome-dark.png') : require('../assets/welcome-light.png')} className={styles.welcomeImage} />
          <h2>Well done, {escape(userDisplayName)}!</h2>
          <div>{environmentMessage}</div>
          <div>Web part property value: <strong>{escape(description)}</strong></div>
        </div>

        {/* --- CUSTOM ENVIRONMENT VARIABLES BLOCK --- */}
        <div style={{ backgroundColor: '#e1dfdd', padding: '15px', margin: '20px 0', borderRadius: '4px', color: '#323130' }}>
          <h3 style={{ marginTop: 0 }}>Environment Variables Test</h3>
          <p style={{ margin: '5px 0' }}><strong>Environment:</strong> {process.env.SPFX_ENVIRONMENT}</p>
          <p style={{ margin: '5px 0' }}><strong>API Base URL:</strong> {process.env.SPFX_API_BASE_URL}</p>
          <p style={{ margin: '5px 0' }}><strong>App Insights Key:</strong> {process.env.SPFX_APP_INSIGHTS_KEY}</p>
        </div>
        {/* ---------------------------------------- */}
      </section>
    );
  }
}

Step 7 — Running and Building for Different Environments
Now, you can easily switch between environments using cross-env. You can add these commands directly to the "scripts" section of your package.json:

"scripts": {
  "serve": "cross-env NODE_ENV=dev gulp serve",
  "build:prod": "cross-env NODE_ENV=prod gulp bundle --ship && gulp package-solution --ship"
}

Then run the gulp serve command. In the SPFx web part, you’ll see the environment variables we defined:

Method 4: Webpack DefinePlugin — Injecting Variables at Build Time

The Webpack DefinePlugin is the engine behind method 3. Sometimes it’s useful to understand it directly, especially for CI/CD pipelines where you want the pipeline itself to inject values.

Here’s a standalone example:

// gulpfile.js
build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfig) => {
    const isDebugMode = generatedConfig.plugins
      .find(p => p instanceof webpack.DefinePlugin)
      ?.definitions?.DEBUG;

    generatedConfig.plugins.find(p => p instanceof webpack.DefinePlugin)
      .definitions['process.env.API_ENDPOINT'] = isDebugMode
        ? JSON.stringify('https://dev-api.contoso.com')
        : JSON.stringify(process.env.API_ENDPOINT);

    return generatedConfig;
  }
});

In this case, during gulp serve (debug mode), it uses the dev URL. During gulp bundle --ship (production), it reads from the OS environment variable API_ENDPOINT — which in a DevOps pipeline you’d set as a secret pipeline variable.

This is perfect for things like:

• Azure Application Insights instrumentation keys
• Backend API endpoints
• Feature flags

Method 5: SPFx 1.22+ with Heft (New Build System)

If you’re starting a fresh project with SPFx 1.22 or later, you’ll notice that gulp has been replaced by Heft as the default build system. Heft is a config-driven task orchestrator from Rush Stack that Microsoft now recommends for all new projects.

With Heft, you can’t use gulpfile.js the same way. Here are the main approaches.

The Recommended Approach: Webpack Patch Plugin

Microsoft’s official way to customize WebPack in Heft projects is through a webpack-patch.json config file.

Step 1: Create the JSON Configuration File

In your project’s config folder, create a new file named webpack-patch.json and add the following content:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/webpack-patch.schema.json",
  "patchFiles": ["./config/webpack-patch/env-inject.js"]
}

Step 2: Create the JavaScript Patch File

You need to create a new folder inside the config folder to hold your script.

• Create a folder named webpack-patch inside the config folder.
• Inside that new folder, create a file named env-inject.js and add this code:

const dotenv = require('dotenv');
const fs = require('fs');
const path = require('path');

// Resolve webpack from your project root — no rig path guessing needed
const webpackPath = require.resolve('webpack', { paths: [path.resolve(__dirname, '../../')] });
const webpack = require(webpackPath);

module.exports = function(webpackConfig) {
  const NODE_ENV = process.env.NODE_ENV || 'dev';
  const envPath = path.resolve(__dirname, `../../env/${NODE_ENV}.env`);

  if (!fs.existsSync(envPath)) {
    console.warn(`Warning: ${envPath} not found. Skipping env injection.`);
    return webpackConfig;
  }

  const envConfig = dotenv.parse(fs.readFileSync(envPath));
  const definitions = {};

  Object.entries(envConfig)
    .filter(([key]) => key.startsWith('SPFX_'))
    .forEach(([key, value]) => {
      definitions[`process.env.${key}`] = JSON.stringify(value);
    });

  webpackConfig.plugins.push(new webpack.DefinePlugin(definitions));
  return webpackConfig;
};

Step 3: Install Dependencies and Create Environment Files

Your patch file uses dotenv to parse environment files, so you need to install it.

• Open your terminal and run:

npm install dotenv --save-dev

• In the root of your project (the same level as src and config), create a folder named env.
• Inside the env folder, create a file named dev.env and define your variables. They must start with SPFX_:

SPFX_API_BASE_URL=https://my-dev-api.azurewebsites.net
SPFX_GREETING_MESSAGE=Hello from Dev Environment

Step 4: Add TypeScript Typings (Crucial for SPFx)
By default, TypeScript will throw an error if you try to type process.env.SPFX_API_BASE_URL because it doesn’t know what process.env is. You need to define these types so your SPFx web part compiles successfully.

• In your src folder, create a file named global.d.ts (or open it if it already exists).
• Add the following TypeScript declaration to let the compiler know about your custom variables:

declare interface NodeJS {
  env: {
    NODE_ENV: 'dev' | 'production';
    SPFX_API_BASE_URL: string;
    SPFX_GREETING_MESSAGE: string;
    [key: string]: string | undefined;
  };
}
declare var process: NodeJS;

Step 5: How to Test and Use It

Now you can safely use your environment variables anywhere inside your web part component (e.g., inside src/webparts/yourWebPart/components/YourWebPart.tsx).

• Open your main React component or web part TypeScript file.
• Add a simple HTML tags to render it on the screen:

public render(): React.ReactElement<IHeftProjectProps> {
    const {
      description,
      isDarkTheme,
      environmentMessage,
      hasTeamsContext,
      userDisplayName
    } = this.props;

    return (
      <section className={`${styles.heftProject} ${hasTeamsContext ? styles.teams : ''}`}>
        <div className={styles.welcome}>
          <img alt="" src={isDarkTheme ? require('../assets/welcome-dark.png') : require('../assets/welcome-light.png')} className={styles.welcomeImage} />
          <h2>Well done, {escape(userDisplayName)}!</h2>
          <div>{environmentMessage}</div>
          <div>Web part property value: <strong>{escape(description)}</strong></div>
        </div>
        
        {/* --- CUSTOM ENVIRONMENT VARIABLES BLOCK --- */}
        <div style={{ backgroundColor: '#f4f4f4', padding: '15px', marginTop: '20px', borderRadius: '4px' }}>
          <h3>Environment Variables Test</h3>
          <p><strong>Greeting:</strong> {process.env.SPFX_GREETING_MESSAGE}</p>
          <p><strong>API Base URL:</strong> {process.env.SPFX_API_BASE_URL}</p>
        </div>
        {/* ---------------------------------------- */}

      </section>
    );
  }

To test the dev.env variables, simply run your standard Heft command. Because the script defaults to dev, it will automatically pick up dev.env

heft start

Note: If you want to test a production environment (e.g., prod.env), you would run cross-env NODE_ENV=prod npm run build (assuming you have cross-env installed and configured in your package.json scripts)

Alternative: Pre-Build TypeScript Generation (Type-Safe)

If you want full TypeScript type safety and IDE autocomplete on your environment variables, this is the cleanest approach.

Create scripts/generate-env-config.js:

const fs = require('fs');
const dotenv = require('dotenv');

const NODE_ENV = process.env.NODE_ENV || 'dev';
const envConfig = dotenv.parse(fs.readFileSync(`./env/${NODE_ENV}.env`));

const spfxVars = Object.entries(envConfig)
  .filter(([key]) => key.startsWith('SPFX_'))
  .map(([key, value]) => `  ${key}: '${value}'`)
  .join(',\n');

const output = `// AUTO-GENERATED — Do not edit manually
export const ENV_CONFIG = {
${spfxVars}
} as const;
`;

fs.writeFileSync('src/utils/envConfig.generated.ts', output);
console.log('Environment config generated successfully.');

Update package.json scripts:

"scripts": {
  "generate-env": "node scripts/generate-env-config.js",
  "start:dev": "cross-env NODE_ENV=dev npm run generate-env && heft start",
  "start:prod": "cross-env NODE_ENV=prod npm run generate-env && heft start"
}

Use it in your components:

import { ENV_CONFIG } from '../utils/envConfig.generated';

// Full autocomplete and type checking!
const apiUrl = ENV_CONFIG.SPFX_API_BASE_URL;
const timeout = ENV_CONFIG.SPFX_API_TIMEOUT;

The generated file is committed to .gitignore and rebuilt every time you run the start script.

Choosing the Right Method

Here’s a quick summary of when to use what:

Common Mistakes to Avoid

• Committing .env files to Git. Always add .env, *.env, and env/ to .gitignore.
• Forgetting the SPFX_ prefix. Variables without this prefix often end up as undefined at runtime.
• Using require('webpack') in Heft projects. This causes silent build failures. Use the SPFx rig import instead.
• Not providing fallback values. Always use process.env.MY_VAR || 'fallback' so your build doesn’t break in environments where the variable isn’t set.
• Expecting runtime env access. Remember — DefinePlugin replaces values at build time, not runtime. The browser never sees process.env; it only sees the already-substituted string.

Conclusion

I hope you found this article helpful. In this guide, I explained different ways to use environment variables in SPFx. I covered built-in variables, PowerShell options, .env files, and Webpack methods. I also shared recommended approaches and alternatives for different scenarios.

If you are working on SPFx projects, choose the method that fits your setup and needs. Start with simple options and move to advanced ones as required. Using environment variables will make your solution more flexible and easier to manage.

Also, you may like:

• SharePoint Framework: CRUD Operations using ReactJS
• PnP React Pagination Control in SharePoint Framework (SPFx) Web Part
• SPFx Fluent UI React Control: ChoiceGroup and Checkbox
• Fluent UI React ComboBox Control in SPFx

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

With SPFx v1.22, Microsoft replaced the Gulp-based toolchain with Heft — a config-driven build orchestrator from the Rush Stack ecosystem. Starting with SPFx v1.23, all new projects will use Heft by default. And by v1.24, the Gulp-based pipeline will be officially unsupported.

So if you have existing projects still running on Gulp, now is the time to migrate. In this tutorial, I will explain how to migrate from a Gulp-based to a Heft-based toolchain in the SharePoint Framework (SPFx) step by step.

What is Heft in SharePoint Framework?

In SPFx (SharePoint Framework), Heft is basically a build and task management tool that helps run and organize all the behind-the-scenes processes when you develop a SharePoint solution.

Think of Heft as a modern replacement for older tools like Gulp in SPFx. Starting from SPFx v1.22, Microsoft officially switched from Gulp to Heft to make builds cleaner and faster.

When you’re building an SPFx project, a lot of things need to happen automatically:

• Compile TypeScript → JavaScript
• Bundle your code
• Run linting (check code quality)
• Execute tests
• Build the final package ready for SharePoint

Heft handles all of this automatically — you just run one command like heft build or heft start, and it takes care of the rest behind the scenes.

Instead of writing custom task scripts like you used to with Gulp, Heft uses simple JSON configuration files to define what to do, making your project easier to maintain and understand.

A new SPFx project already comes pre-configured with Heft through something called a rig (a shared settings package). So you don’t need to set anything up yourself — it just works out of the box.

Here’s a quick comparison between Gulp and Heft.

Heft makes SPFx development cleaner and more modern by replacing the old Gulp-based system with a structured, configuration-driven approach.

Check out Set Up Your SharePoint Framework (SPFx) Development Environment using Heft Toolchain

Before You Start — A Few Things to Check

Don’t jump straight to uninstalling packages. Do these first:

• Back up your project. Either copy the folder or make sure all your code is committed to source control. The migration makes sweeping changes to your config files and package.json.
• Check your Node.js version. SPFx v1.22 requires Node v22. Run node -v to confirm. If you’re on an older version, update first.
• Check for gulp customizations. Open your gulpfile.js and look for any custom tasks — things like build.configureWebpack.mergeConfig(), build.rig.addPreBuildTask(), or custom copy/lint steps. You’ll need to translate these to Heft plugins after the migration. Note these down before you delete anything.

Migrate from Gulp based to Heft based Toolchain in SPFx

Follow the steps below to migrate from Gulp based to Heft based Toolchain in SharePoint Framework (SPFx).

Step 1: Uninstall the Gulp Toolchain

The first thing to do is rip out the old Gulp-based packages. Run this command from your project root:

npm uninstall @microsoft/sp-build-web ajv gulp

Next, uninstall the TypeScript compiler wrapper. The default SPFx v1.21.1 project uses TypeScript 5.3, so:

npm uninstall @microsoft/rush-stack-compiler-5.3

If your project uses a different TypeScript version, replace 5.3 with whatever version you have. Check your package.json devDependencies — look for @microsoft/rush-stack-compiler-*.

Step 2: Install the Heft Toolchain

Now install all the Heft-related packages your project needs:

npm install @microsoft/spfx-web-build-rig@1.22.1 @microsoft/spfx-heft-plugins@1.22.1 @microsoft/eslint-config-spfx@1.22.1 @microsoft/eslint-plugin-spfx@1.22.1 @microsoft/sp-module-interfaces@1.22.1 @rushstack/eslint-config@4.5.2 @rushstack/heft@1.1.2 @types/heft-jest@1.0.2 @typescript-eslint/parser@8.46.2 --save-dev --save-exact --force

That --force flag is there because some peer dependency conflicts can pop up during migration. It’s fine to use here — you’re intentionally replacing the old toolchain.

If you also want to upgrade TypeScript to v5.8 (optional but recommended), run:

npm install typescript@~5.8.0 --save-dev

Heads up: If you run into issues installing TypeScript v5.8 during migration, you can skip this for now. The toolchain works fine with TypeScript v5.3 too.

Step 3: Update Your NPM Scripts

Open your package.json and replace the old Gulp-based scripts with Heft equivalents. Find the scripts section and update it like this:

{
  "scripts": {
    "build": "heft build --clean",
    "clean": "heft clean",
    "test": "heft test",
    "test-only": "heft run --only test --",
    "deploy": "heft dev-deploy",
    "start": "heft start --clean",
    "build-watch": "heft build --lite",
    "package-solution": "heft package-solution",
    "deploy-azure-storage": "heft deploy-azure-storage",
    "eject-webpack": "heft eject-webpack",
    "trust-dev-cert": "heft trust-dev-cert",
    "untrust-dev-cert": "heft untrust-dev-cert"
  }
}

Here’s how the old Gulp commands map to Heft:

Read How to Change Solution Name in SPFx

Step 4: Add the SPFx Heft Rig

Heft uses a concept called rigs — shared build configurations that multiple projects can extend. This is what replaces the old sp-build-web rig from the Gulp days.

Create a new file at ./config/rig.json with this content:

{
  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
  "rigPackageName": "@microsoft/spfx-web-build-rig"
}

This one file tells Heft: “use the SPFx web build rig for all the default build settings.” You don’t have to define TypeScript paths, Webpack entry points, or ESLint configs from scratch — the rig handles all of that for you.

Step 5: Replace the Sass Configuration

Open ./config/sass.json and replace everything in it with:

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft-sass-plugin.schema.json",
  "extends": "@microsoft/spfx-web-build-rig/profiles/default/config/sass.json"
}

This hooks your project’s Sass compilation into the Heft Sass plugin defined by the rig. If you had custom Sass settings in the old file (like useCSSModules or postProcessedFileExtensions), you can add those back here — they’ll override the rig’s defaults.

Step 6: Add the TypeScript Plugin Configuration

Create a new file at ./config/typescript.json:

{
  "extends": "@microsoft/spfx-web-build-rig/profiles/default/config/typescript.json",
  "staticAssetsToCopy": {
    "fileExtensions": [".resx", ".jpg", ".png", ".woff", ".eot", ".ttf", ".svg", ".gif"],
    "includeGlobs": ["webparts/*/loc/*.js"]
  }
}

The staticAssetsToCopy section tells Heft which non-TypeScript files to copy over during the build. This replaces what gulp copy-assets or similar custom tasks used to handle. Adjust the file extensions and globs to match whatever your project actually needs.

Check out How to Install NVM in Windows

Step 7: Update tsconfig.json

Replace the contents of your existing ./tsconfig.json with this:

{
  "extends": "./node_modules/@microsoft/spfx-web-build-rig/profiles/default/tsconfig-base.json"
}

Your old tsconfig.json probably had a long list of compiler options. All of those are now inherited from the rig’s base config. You only need to add project-specific overrides here if you have them.

Step 8: Delete gulpfile.js

Just delete it.

rm gulpfile.js

If you had custom tasks in your gulpfile.js — like custom Webpack config, pre-build steps, or post-build file operations — don’t delete it yet. Keep it open in a separate window for reference while you set up the equivalent Heft plugins in the next section.

Step 9: Upgrade Your SPFx Production Dependencies

Update the core SPFx packages to v1.22:

npm install @microsoft/sp-component-base@1.22.1 @microsoft/sp-core-library@1.22.1 @microsoft/sp-lodash-subset@1.22.1 @microsoft/sp-office-ui-fabric-core@1.22.1 @microsoft/sp-property-pane@1.22.1 @microsoft/sp-webpart-base@1.22.1 --save-exact

After making so many changes to packages, I’d strongly recommend doing a full clean reinstall:

# Windows (PowerShell)
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json

# Mac/Linux
rm -rf node_modules package-lock.json

# Then reinstall everything cleanly
npm install

This ensures your dependency tree is consistent and you’re not carrying over any stale Gulp-related packages.

Step 10: Test the Migration

Run a build to verify everything works:

npm run build

Or if you have Heft installed globally:

heft build --production

If the build completes without errors, you’re done with the core migration. Fire up the dev server with:

npm run start
# or
heft start --clean

This will automatically open the workbench url. In case you are getting an error like in the image below.

Just run the following command.

npm run trust-dev-cert

Then, re-run the npm run start command; this time, without errors, you can get your web part as shown below.

Handling Custom gulpfile.js Tasks

This is where it gets more involved. If your old gulpfile.js was just the default SPFx boilerplate, you’re done. But if you had custom tasks, here’s how to handle the most common ones:

Custom Webpack Configuration

If you were using build.configureWebpack.mergeConfig() to inject custom Webpack settings, you have two options in Heft:

Option 1 — Use the webpack patch file (simpler):

Create a file at ./config/webpack.extend.js:

module.exports = function (existingConfig) {
  existingConfig.resolve = existingConfig.resolve || {};
  existingConfig.resolve.alias = {
    ...existingConfig.resolve.alias,
    '@myAlias': require('path').resolve(__dirname, '../src/helpers')
  };
  return existingConfig;
};

Then reference it in your heft.json (more on that file below).

Option 2 — Eject Webpack entirely (for complex cases):

heft eject-webpack

This generates a full webpack.config.js in your project that you can modify directly. It’s the escape hatch for when you need complete control.

Custom Pre/Post Build Tasks

If you had build.rig.addPreBuildTask() or addPostBuildTask() For things like copying extra files or running scripts, use Heft’s run-script-plugin.

Create ./config/heft.json:

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
  "extends": "@microsoft/spfx-web-build-rig/profiles/default/config/heft.json",
  "phasesByName": {
    "build": {
      "tasksByName": {
        "my-custom-script": {
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft",
            "pluginName": "run-script-plugin",
            "options": {
              "scriptPath": "./scripts/my-custom-task.js"
            }
          }
        }
      }
    }
  }
}

Create ./scripts/my-custom-task.js and put your custom logic there. This script runs as part of the build phase.

Copying Files

The old build.copyStaticAssets type of operations now live in typescript.json under staticAssetsToCopy (which we already configured in Step 6). For more complex copy scenarios, use the copy-files-plugin in heft.json.

Common Issues and Fixes

A few things that tend to trip people up during migration:

• ESLint errors after migration: Your old .eslintrc.js may reference @microsoft/eslint-config-spfx in a way that conflicts with the new package. Update the extends in your ESLint config to use @rushstack/eslint-config and re-run the build.
• “Cannot find module” errors: Usually means stale node_modules. Do the clean reinstall from Step 9.
• TypeScript errors you didn’t have before: If you upgraded to TypeScript v5.8, some stricter type checks may now flag issues that were silently ignored before. Fix them or stay on TypeScript v5.3 for now.
• PnP SPFx Controls not working: If you use @pnp/spfx-controls-react, make sure you’re on a version that supports SPFx v1.22. Run npm ls @pnp/spfx-controls-react to check your current version and compare with their release notes.
• Dev cert issues: If HTTPS fails on the local workbench, run heft trust-dev-cert to re-trust the certificate.

Using the M365 CLI to Generate an Upgrade Report (Optional but Helpful)

If you want a full list of every change needed for your specific project before you manually edit anything, the Microsoft 365 CLI can generate an upgrade report for you:

# Install M365 CLI if you don't have it
npm i -g @pnp/cli-microsoft365

# Generate the upgrade report
m365 spfx project upgrade --toVersion 1.22.0 --preview --output md > upgrade-report.md

Open upgrade-report.md — it will list every dependency that needs to change, every script to update, and any manual steps specific to your project. It’s a great way to audit before you start making changes.

What the Final Project Structure Looks Like

After migration, here’s what your key config files should look like:

your-spfx-project/
├── config/
│   ├── rig.json          ← NEW (points to spfx-web-build-rig)
│   ├── heft.json         ← NEW (only if you have custom tasks)
│   ├── sass.json         ← UPDATED (now extends rig)
│   ├── typescript.json   ← NEW (configures TS plugin)
│   └── package-solution.json (unchanged)
├── tsconfig.json         ← UPDATED (now extends rig's base config)
├── package.json          ← UPDATED (scripts use heft commands)
├── gulpfile.js           ← DELETED
└── src/                  (unchanged)

Wrapping Up

In this tutorial, I explained how to migrate from Gulp based toolchain to Heft based toolchain in the SharePoint Framework (SPFx). Follow the above steps, and you should be able to migrate your project.

The key things to remember:

• Uninstall the old Gulp packages and install the Heft equivalents
• Add rig.json to point to @microsoft/spfx-web-build-rig
• Update your config files (sass.json, typescript.json, tsconfig.json)
• Replace your npm scripts with heft commands
• Delete gulpfile.js (but migrate any custom tasks first)
• Do a clean npm install at the end to flush out any stale dependencies

If you’ve got custom Gulp tasks, the translation to Heft plugins takes a bit of extra thought — but the run-script-plugin and copy-files-plugin cover most real-world scenarios.

Also, you may like:

• Create a Modal Popup in SPFx
• Bind SharePoint List Items to SPFx Fluent UI React Dropdown
• Customize SharePoint List Command Bar Download Button Using SPFx Extension
• Upload File to SharePoint Document Library With Metadata in SPFx

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

With SPFx 1.22, things have changed. Microsoft has introduced a new build system called Heft, which replaces Gulp and handles the build process more structurally.

I’m going to walk you through every step — explain what each tool actually does, why you’re installing it, and flag the important gotchas along the way. By the end, your machine will be fully ready to build real SharePoint solutions.

This tutorial walks you through setting up your SPFx development environment using the Heft toolchain step by step. After this, i

This Guide Is for SPFx v1.22 and Above (Heft-Based Toolchain)

Here’s something you absolutely need to know before anything else: SPFx v1.22 introduced a brand-new toolchain called Heft, replacing the older Gulp-based build system that was used from SPFx v1.0 all the way through v1.21.1.

This matters because:

• If you’re building on SPFx v1.22 or newer → you’re on the Heft-based toolchain. This guide is for you.
• If you’re building on SPFx v1.0 through v1.21.1, including any on-premises SharePoint Server deployment → you’re on the Gulp-based (legacy) toolchain. Then check this: Set up your SharePoint Framework Gulp-based development environment.

Not sure which version you need? If you’re building for SharePoint Online with no constraints, just follow this guide — it uses the latest SPFx. If you need to support a specific version of SharePoint Server on-premises, check the version number requirements first before installing anything.

The toolchain change is significant. Build configurations, commands, and customizations all changed between these two toolchains. The command you’ll use to run your project locally, for example, is heft in the new toolchain — not gulp serve. I’ll cover all of that clearly as we go.

Let’s first understand what Heft is in SPFx.

What is Heft in SharePoint Framework (SPFx) and Why Do We Need This?

In SharePoint Framework (SPFx), Heft is the modern tool that handles everything required to build and package your solution. Earlier, SPFx relied on Gulp, which required developers to manage multiple tasks and configurations manually.

Heft simplifies this by providing a standardized and optimized way to run all build-related activities with minimal setup. For a beginner, you can think of Heft as the system that quietly takes your code, processes it, and prepares it so SharePoint can use it.

When you work on an SPFx project, you typically write code in TypeScript and use modern libraries like React. However, SharePoint cannot directly use that raw code. This is where Heft comes in. It compiles your code, bundles all the files together, checks for errors, and prepares the final package that can be deployed. All of this happens behind the scenes when you run simple commands in your terminal.

Heft provides a set of commands that you’ll use regularly during development. The most common one is:

• heft build → Compiles your project and prepares the build output.

If you want to remove old build files and start fresh, you can use:

• heft clean → Deletes previously generated files and clears the build cache.

For local development, especially when testing your web part in the browser, you’ll use:

• heft start → Starts the local development environment and serves your solution.

Once your solution is ready, you need to package it so it can be deployed to SharePoint. For that, Heft provides:

• heft package-solution → Creates the .sppkg file used for deployment.

If you’re preparing your solution for production, you should use:

• heft package-solution --production → Generates an optimized, production-ready package.

During development, especially when testing locally over HTTPS, you might need:

• heft trust-dev-cert → Installs and trusts a development certificate for secure local testing.

In simple terms, Heft is what keeps your SPFx development smooth and consistent. Instead of worrying about how your code is compiled or packaged, you just run these commands, and Heft takes care of the rest. As you grow more comfortable with SPFx, you might explore customizing Heft, but for most developers—especially beginners—it works perfectly out of the box.

Check out How to Change Solution Name in SPFx

Set Up Your Microsoft 365 Tenant First

SPFx solutions run in SharePoint Online, so you need somewhere to test them. Before following the installation steps below, make sure you have a Microsoft 365 tenant ready. If you don’t have one, go to developer.microsoft.com and sign up for the free Microsoft 365 Developer Program — it gives you a sandbox tenant you can use freely for development.

You Can Use Any Operating System

One of the great things about SPFx is that you are not locked into Windows. You can use macOS, Windows, or Linux — all are fully supported.

Step 1: Install Node.js v22 LTS

The first thing to install is Node.js. Think of Node.js as the engine that powers all the SPFx developer tools. Without it, nothing else will work.

The version you need is Node.js v22 LTS (also known by its codename “Jod”).

This is the recommended version for SPFx v1.22.*. If you’re working on a project using a different SPFx version, verify that your Node.js version is supported for that particular SPFx release before installing.

LTS vs. Current — What You Need to Know

Node.js always maintains two release tracks simultaneously:

• LTS (Long Term Support): Stable, thoroughly tested, and the version that SPFx officially supports.
• Current: Has newer features but is not supported by SPFx. Avoid it for SPFx development.

Always install an LTS version. SPFx is only supported on LTS versions of Node.js, so do not install the “Current” release even if it looks newer on the Node.js website.

How to Download Node.js

Here’s how to find the right installer:

• Go to the Node.js website (nodejs.org) and navigate to the Downloads page to find a specific version.
• Windows users: Look for the .msi installer files. There are usually two — one for x86 and one for x64 systems. The filenames look like node-v{version-number}-x86.msi or node-v{version-number}-x64.msi. Most modern Windows machines are 64-bit, so you’ll want the x64 version.
• macOS users: Look for the .pkg installer, usually named node-v{version-number}.pkg.

Verify Your Installation

After installing Node.js, open your terminal (Command Prompt or PowerShell on Windows, Terminal on macOS/Linux) and run:

node --version

You should see a version number like v22.x.x. If that appears, Node.js is successfully installed, and you’re ready to move on.

Already have Node.js installed? Run node --version first. If you have v22 LTS already, you’re good to go. If you have a different version and need to work with multiple SPFx versions across different projects, consider using Node Version Manager (NVM) — more on that later.

Read How to Create a Modal Popup in SPFx

Step 2: Install a Code Editor

Next, you need a code editor to write your TypeScript and configuration files. You can use any editor you’re comfortable with — SPFx has no requirement here.

That said, I recommended using Visual Studio Code (VS Code) for all its examples, and I’d strongly recommend it for beginners and experienced developers alike. It’s free, cross-platform, has a built-in terminal (which is super handy for running SPFx commands without switching windows), and has excellent extension support.

If you prefer WebStorm from JetBrains, that’s also a perfectly valid choice.

Download VS Code from code.visualstudio.com and install it for your platform.

Step 3: Install the Development Toolchain Prerequisites

This is the most important step of the entire setup. SPFx’s build and development toolchain relies on several open-source tools. While most project-level dependencies install automatically when you create a new project, there are three tools you need to install globally on your machine:

1. Heft — the build tool (new in SPFx v1.22)
2. Yeoman (yo) — the project scaffolding wizard
3. Yeoman SharePoint Generator — the SPFx-specific plugin for Yeoman

Microsoft gives you a helpful shortcut — you can install all three with a single command:

npm install @rushstack/heft yo @microsoft/generator-sharepoint --global

Or, if you prefer to install them one at a time and understand what each does, here’s the breakdown:

Install Heft

Heft is the new build toolchain introduced with SPFx v1.22. It replaces Gulp as the primary build engine and orchestrates other popular tools like TypeScript, ESLint, Jest, Webpack, and API Extractor under the hood. If you’re familiar with task runners like Gulp or Grunt, Heft plays a very similar role — but it’s designed for large-scale, consistent use across many projects.

To install Heft globally:

npm install @rushstack/heft --global

Why install it globally? Technically, Heft doesn’t need to be installed globally — it’s included inside each project you create. But installing it globally makes it much easier to run Heft commands directly from your terminal without navigating into each project’s local binaries. The Microsoft documentation recommends global installation for this reason.

Important — What if you’re on SPFx v1.21.x or older? You should not install Heft. Older projects use the Gulp-based toolchain, and their setup guide tells you to install gulp-cli globally instead. The tools are different, the commands are different, and mixing them up will cause confusion.

Install Yeoman

Yeoman (yo) is a project scaffolding tool. It asks you a series of questions in an interactive wizard and then automatically generates a complete, correctly structured SPFx project for you — with all the right folders, TypeScript configuration, build settings, and boilerplate code already in place.

To install Yeoman globally:

npm install yo --global

Install the Yeoman SharePoint Generator

The Yeoman SharePoint Generator is the SPFx-specific plugin that powers the wizard when you create a new project. Without it, Yeoman wouldn’t know how to scaffold an SPFx solution. It’s what makes Yeoman ask you things like “What type of component do you want to create?” and “Which JavaScript framework do you want to use?”

To install it globally:

npm install @microsoft/generator-sharepoint --global

Check out Bind SharePoint List Items to SPFx Fluent UI React Dropdown

Step 4: Install a Modern Web Browser

You’ll need a modern web browser for testing and debugging your solutions in the SharePoint workbench. The Microsoft documentation recommends any of the following:

• Microsoft Edge
• Google Chrome
• Firefox

All three are excellent choices with strong developer tools. Avoid Internet Explorer — it’s not supported for SPFx development.

Step 5: Trust the Self-Signed Developer Certificate

When you test an SPFx solution locally, it runs on a local development server that uses HTTPS by default. This local server uses a self-signed SSL certificate — a certificate that isn’t issued by a trusted certificate authority. By default, your operating system and browser will not trust this certificate, which means you’ll get a security warning or blocked page when you try to load the workbench.

To fix this, you need to register the certificate as trusted on your machine. SPFx includes a built-in Heft command to do this.

When to Run This Command

You can run this command either now or after you create your first project. I recommend running this command after you create your first project. The command needs to be run from inside an SPFx project folder (after running npm install to install the project dependencies), so if you haven’t created a project yet, you can come back to this step.

Once you have a project created and npm install has been run inside the project root, execute:

heft trust-dev-cert

Note for SPFx v1.21.x and older (Gulp-based projects): The equivalent command in the old toolchain was gulp trust-dev-cert. If you’re working on a legacy project, use the Gulp command instead.

You only need to do this once per machine. After the certificate is trusted, all future SPFx projects on the same machine will work without needing to repeat this step.

Check out Customize SharePoint List Command Bar Download Button Using SPFx Extension

Step 6: Set the SPFX_SERVE_TENANT_DOMAIN Environment Variable (Optional but Recommended)

Starting with SPFx v1.17, the hosted workbench URL used during development was changed to use a dynamic placeholder. If you open a project’s ./config/serve.json file, you’ll see this:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "initialPage": "https://{tenantDomain}/_layouts/workbench.aspx"
}

Notice the {tenantDomain} placeholder. When you run the serve command to test your solution, SPFx automatically replaces this placeholder with the value of an environment variable called SPFX_SERVE_TENANT_DOMAIN on your system.

This is useful because it means you configure your SharePoint tenant domain once at the operating system level, and every SPFx project you create picks it up automatically. You won’t need to manually edit the serve.json file in every project.

The variable supports not just the tenant domain but also full site URLs in other serve configurations — for example, if you’re building a Field Customizer and have a pageUrl in your serve config with a {tenantDomain} placeholder, it will be replaced the same way.

How to Set It

On Windows:

1. Press Win + S and search for “Environment Variables”
2. Click “Edit the system environment variables”
3. Under “User variables”, click “New”
4. Set the Variable name to SPFX_SERVE_TENANT_DOMAIN
5. Set the Variable value to your SharePoint tenant domain, e.g., contoso.sharepoint.com
6. Click OK and restart your terminal

On macOS/Linux:
Add the following line to your shell profile file (~/.zshrc for Zsh, ~/.bashrc for Bash):

export SPFX_SERVE_TENANT_DOMAIN=contoso.sharepoint.com

Then restart your terminal or run source ~/.zshrc to apply the change immediately.

Read Upload File to SharePoint Document Library With Metadata in SPFx

Quick Verification: Are All Your Tools Installed?

Once you’ve completed the steps above, you can verify everything is in place by running this command in your terminal:

npm list --global --depth=0

This lists all globally installed npm packages. You should see:

• @rushstack/heft
• yo
• @microsoft/generator-sharepoint

If any of these are missing, re-run the install command for that specific package.

Develop Your First Client-Side Web Part using SPFx

With all the tools installed and your developer certificate trusted, your machine is completely set up for SharePoint Framework development. The next step is scaffolding your very first SPFx project. Now we will create our first SPFx client-side web part.

You can also create a folder:

md SPFxHeftProject
cd SPFxHeftProject

Open your terminal, navigate to the folder where you’d like to create the project, and run:

yo @microsoft/sharepoint

Yeoman will launch an interactive wizard. It will ask you for your solution name, the type of component you want to create (web part, extension, etc.), and your preferred JavaScript framework.

When prompted:

• What is your solution name? sp-fx-heft-project
• Which type of client-side component to create? WebPart
• Add new Web part to solution sp-fx-heft-project.
• What is your Web part name? HeftProject
• Which template would you like to use? React

Here is a screenshot for your reference.

Understand What Just Changed

When the generator runs, it defaults to the Heft-based toolchain. You’ll notice immediately that the generated project looks slightly different from older projects:

• There’s no gulpfile.js
• There’s a ./config/rig.json file
• There’s a ./config/sass.json that extends the rig configuration
• There’s a ./config/typescript.json for TypeScript plugin settings
• The package.json scripts call heft instead of gulp

This confirms you’re using the new Heft-based build system. This is the key difference compared to older SPFx projects. The Gulf file is also not there.

Your new package.json scripts section will look like this:

  "scripts": {
    "build": "heft test --clean --production && heft package-solution --production",
    "start": "heft start --clean",
    "clean": "heft clean",
    "eject-webpack": "heft eject-webpack"
  }

You can refer to the screenshot below:

Notice a couple of things here. First, the bundle task is gone — in Heft, build handles both building and bundling in one step. Second, there’s a brand new deploy command (heft dev-deploy) that didn’t exist in the Gulp world.

After npm install finishes, if you haven’t already, run:

heft trust-dev-cert

Update the Workbench URL

Before testing your web part, make sure to update the initialPage in the serve.json file. Replace {tenantDomain} with your actual SharePoint tenant URL so the local workbench opens correctly in your environment. You can check the screenshot below.

Run the Project

Instead of the old Gulp command:

gulp serve

You now use:

npm run start
# or
heft start --clean

After running the command, the local workbench will open in your browser. At this point, you may see a prompt asking “Allow debug scripts?”. This is expected when running SPFx solutions locally, as the page is loading scripts from your development machine.

Since you are testing your own code, you can safely click “Load debug scripts” to proceed and continue testing your web part.

Then, the page below will open. Click the + Add icon and find your web part. You can either search for your web part name, and it will display.

Once you’re confident that your SPFx web part is working as expected, the next step is to prepare it for deployment. Run the command below to create the package, and once it completes, you’ll find the .sppkg file inside the sharepoint folder, as shown in the image below.

heft package-solution --production

Now upload the generated .sppkg file to your tenant app catalog or site collection app catalog. The deployment process remains the same as before, so you can follow the usual steps you’ve already used for deploying SPFx solutions.

The Building Blocks: Actions, Phases, Tasks, and Rigs

Now you need to understand how Heft organizes work. It has a specific vocabulary, and once you know these four terms, everything clicks.

• Actions are the top-level commands you run from the CLI. For example, heft build, heft test, heft start. These are similar to the gulp tasks you used to have.
• Phases are logical groupings of work within an action. The build action might contain a build phase and a test phase.
• Tasks live inside phases. A task is a single unit of work — like compiling TypeScript, compiling Sass, or running ESLint.
• Rigs are the really clever part. A rig is a shared, reusable configuration package. Instead of every SPFx project carrying its own massive heft.json file with all the build logic, your project points to a rig package (@microsoft/spfx-web-build-rig) that contains all the default build configuration. Your project only defines what’s different from the default.

In practice, a new SPFx v1.22 project has a very lean ./config/rig.json file that looks like this:

{
  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
  "rigPackageName": "@microsoft/spfx-web-build-rig"
}

That single file tells Heft: “use all the build phases, tasks, and configurations defined in the SPFx rig package.” Clean and simple.

Read Build a Custom Slides Manager in SPFx Web Part Property Pane

Heft vs. Gulp — A Clear Summary

Since this distinction causes a lot of confusion, let me summarize it clearly in one place:

If you’ve been using the old toolchain, here’s the side-by-side comparison you need:

If you’re starting fresh with SharePoint Online, always use the Heft-based toolchain. If you open someone else’s older project, check the SPFx version in package.json to know which toolchain applies.

Manage Multiple SPFx Versions on One Machine

As you work on more projects over time, you may encounter situations where different projects require different SPFx versions — and therefore different Node.js versions. This is common when maintaining legacy solutions alongside new ones.

The Microsoft documentation suggests these approaches:

• Node Version Manager (NVM): Install multiple Node.js versions side-by-side and switch between them with a single command. For macOS/Linux, use nvm. For Windows, use nvm-windows. This is the most practical approach for most developers.
• Virtual Machines: Run each environment in a completely isolated VM.
• Docker: Use Docker containers to fully isolate each environment.

For most developers, NVM is the simplest solution. Once it’s installed, switching Node.js versions is as easy as typing nvm use 22 or nvm use 18.

Conclusion

In this tutorial, I explained how to set up your SPFx development environment using the Heft toolchain step by step. The key things to remember are: use Node.js v22 LTS, install the Heft toolchain (not Gulp) since you’re on SPFx v1.22+, and trust your developer certificate before testing locally. If you ever switch machines or work with an older project that uses SPFx v1.21.1 or below, refer back to the Gulp-based setup guide — the commands and tools are different.

From here, every SPFx project you scaffold will follow the same pattern: run yo @microsoft/sharepoint, answer the wizard, run npm install, and start building.

Do let me know in the comments below if you face any issues.

You may also like the following tutorials:

• Build a SharePoint Folder Tree View Using SharePoint Framework (SPFx)
• SharePoint Framework (SPFx) Interview Questions and Answers
• Display SharePoint List Items in SPFx Web Part
• Fluent UI React Dropdown in SharePoint Framework (SPFx)

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

In this tutorial, I will show you how to change the SPFx solution name that every developer is looking for. I will explain in detail which files you need to modify.

I’ll walk you through two methods:

1. The manual method — editing the files yourself (full control, always works)
2. The CLI for Microsoft 365 method — a single command that does the heavy lifting for you

Let’s get into it.

Why the Solution Name Matters

Before we start changing things, let me quickly explain what the solution name actually affects.

When you build and deploy an SPFx package (.sppkg file) to the SharePoint App Catalog, SharePoint reads the name from your project config to display in the App Catalog’s Title column. That’s the name your site admins and end users will see when they browse available apps.

If you left it as helloworld-webpart-client-side-solution from the Yeoman generator, that’s exactly what shows up in the App Catalog. Not a great look.

The name also shows up in:

• The .sppkg filename itself (the deployed package)
• The Teams app manifest (if you’re targeting Microsoft Teams)
• Internal references inside the solution package

So yes, it’s worth getting right before you deploy.

What Files Store the SPFx Solution Name?

Here’s a quick map of all the places where the name lives in a typical SPFx project:

The most important one is package-solution.json. That’s the one that controls what you see in SharePoint’s App Catalog.

Also check out How to Install NVM in Windows

Method 1: Manual Rename (The Right Way to Understand It)

This is my preferred way when I want full control over which changes and which don’t. It takes about 5 minutes.

Step 1 — Open config/package-solution.json in SPFx Solution

This is the main config file for your solution package. It looks something like this by default:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "helloworld-webpart-client-side-solution-client-side-solution",
    "id": "e1a41469-fed8-47ab-988f-d8236ad26d71",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "developer": {
      "name": "",
      "websiteUrl": "",
      "privacyUrl": "",
      "termsOfUseUrl": "",
      "mpnId": "Undefined-1.22.2"
    },
    "metadata": {
      "shortDescription": {
        "default": "helloworld-webpart-client-side-solution description"
      },
      "longDescription": {
        "default": "helloworld-webpart-client-side-solution description"
      },
      "screenshotPaths": [],
      "videoUrl": "",
      "categories": []
    },
    "features": [
      {
        "title": "helloworld-webpart-client-side-solution Feature",
        "description": "The feature that activates elements of the helloworld-webpart-client-side-solution solution.",
        "id": "6a150251-c8bc-478d-9baa-4bb221f1f157",
        "version": "1.0.0.0"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/helloworld-webpart-client-side-solution.sppkg"
  }
}

There are two things to change here:

Change 1 — The solution name:

"name": "tsinfo-employee-directory-client-side-solution"

This is what shows up in the App Catalog’s Title column. Keep it descriptive. Avoid using SharePoint or Teams feature keywords like “Files”, “Chat”, “Calendar”, etc., since that can confuse users.

Change 2 — The .sppkg filename:

"paths": {
  "zippedPackage": "solution/tsinfo-employee-directory.sppkg"
}

Only update the part after the /. The solution/ folder path stays the same.

Pro tip: You can also add an optional title field inside solution if you want a more human-friendly display name with spaces and special characters:

"title": "Tsinfo Employee Directory"

The title field supports localized strings, while name is the non-localized internal identifier.

In metadata, you can also update the solution name.

Step 2 — Open package.json in SPFx Solution

This is your npm project file in the root of your SPFx project. Find the name field:

{
  "name": "helloworld-webpart-client-side-solution",
  ...
}

Change it to match your new name:

{
  "name": "tsinfo-employee-directory",
  ...
}

Note: npm package names must be lowercase, with no spaces — use hyphens instead.

Step 3 — Open .yo-rc.json in SPFx Solution

This file stores the Yeoman generator’s memory of your project. Open it and look for the solutionName property:

{
  "@microsoft/generator-sharepoint": {
    "solutionName": "helloworld-webpart-client-side-solution",
    ...
  }
}

Update it to your new name:

{
  "@microsoft/generator-sharepoint": {
    "solutionName": "tsinfo-employee-directory",
    ...
  }
}

Step 4 — Update the SPFx Web Part Manifest (Optional but Recommended)

If you also want to rename what appears in the SharePoint web part toolbox (the “add a web part” panel), open the web part manifest file. It’s usually at:

src/webparts/[yourWebPartName]/[YourWebPartName]WebPart.manifest.json

Look for this section:

 "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70",
    "group": { "default": "Advanced" },
    "title": { "default": "helloworld" },
    "description": { "default": "helloworld description" },
    "officeFabricIconFontName": "Page",
    "properties": {
      "description": "helloworld"
    }
  }]

Update the title.default value to your new display name. This is what end users see when they search for your web part.

Step 5 — Rebuild and Repackage The SPFx Solution

After all changes are saved, run the standard build commands:

heft build --clean
heft package-solution --production

This regenerates the .sppkg file with the new name. Upload it to the App Catalog, and you’re done.

Check out Build a Custom Slides Manager in SPFx Web Part Property Pane

Method 2: CLI for Microsoft 365 (The Fast Way)

If you’d rather not touch multiple files manually, the CLI for Microsoft 365 has a dedicated command that handles renaming for you in one shot. This is especially useful when you’re working with a PnP sample and just need a quick rename.

Install (or use without installing)

You can run it without a global install using npx:

npx -p @pnp/cli-microsoft365 -- m365 spfx project rename --newName tsinfo-employees-directory

Or if you have it installed globally:

m365 spfx project rename --newName tsinfo-employees-directory

Make sure you run this command from inside your SPFx project folder.

What This Command Updates Automatically

When you run the rename command, it updates the project name in all of these files at once:

• package.json
• .yo-rc.json
• config/package-solution.json
• config/deploy-azure-storage.json
• README.md

Generate a New SPFx Solution ID (Important for Cloned Projects)

If you’re renaming a project that was cloned or copied from another one (like a PnP sample), you should also generate a fresh solution ID. Two solutions with the same GUID will conflict in the App Catalog:

m365 spfx project rename --newName contoso-employee-directory --generateNewId

The --generateNewId flag creates a brand-new GUID for the id field in package-solution.json. Always use this when renaming a cloned or downloaded sample.

Common Mistakes to Avoid

Here are a few mistakes that you should look at as a SPFx developer while renaming the SharePoint Framework solution name.

• Only changing one file — Forgetting to update package.json or .yo-rc.json won’t break your build, but it creates confusing mismatches between your npm package name and what’s deployed.
• Not repackaging after the rename — Your changes only take effect after you run heft build --clean and heft package-solution --production again.
• Uploading without replacing — When you re-upload the .sppkg to the App Catalog, make sure you check “Replace it” if the old file is still there.
• Using the same GUID for cloned solutions — If you copied a solution from somewhere, always use --generateNewId or manually generate a new GUID. Duplicate IDs cause deployment errors.
• Special characters in the name field — The name property in package-solution.json doesn’t support special characters. If you want spaces or symbols in what users see, use the title field instead.

Which Method Should You Use?

Honestly, if you’re comfortable in VS Code and understand your project structure, the manual method gives you the most clarity and control. You see exactly what changed and why.

If you’re in a hurry or you’re doing this regularly across multiple projects (like spinning up new projects from PnP samples), the CLI for Microsoft 365 method saves real time. The --generateNewId flag especially is a lifesaver if you work with community samples.

Both methods get you to the same end result — a properly renamed, clean SPFx solution ready for deployment.

Conclusion

I hope you found this article helpful! In this tutorial, I explained two methods for renaming an existing SPFx solution, along with example images. Additionally, I also explained which method to use at which time. Follow these methods when you are also trying to rename your SPFx project.

Also, you may like:

• Bind SharePoint List Items to SPFx Fluent UI React Dropdown
• Create a Modal Popup in SPFx
• Customize SharePoint List Command Bar Download Button Using SPFx Extension
• Upload File to SharePoint Document Library With Metadata in SPFx

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

After updating the code, I need to build the package for deployment, but we got stuck because Im using the latest SPFx V1.21.11 and my Node version is V22. But the client’s SPFx solution is using the old version 10. To work on the client solution, I had to downgrade my Node version.

But side by side, Im also working for some other clients who are using the latest versions. In this case, I can’t downgrade or upgrade my Node version every time, which isn’t a good option either.

After researching, I found the best solution: NVM [Node Version Manager], which makes switching between node versions easy with simple commands. In this tutorial, I will explain how to use NVM and how to resolve issues that may arise during installation.

What is NVM?

NVM (Node Version Manager) is a tool that helps you use different versions of Node.js on the same computer. If one project needs an older Node version and another project needs a newer one, NVM lets you switch between them easily using simple commands. You don’t need to uninstall or reinstall Node again and again.

There are two types of NVM:

• nvm-windows = For Windows computers
• nvm-sh = For macOS, Linux, and WSL.

NVM allows you to easily upgrade to the latest Node.js versions while keeping older versions available for legacy projects.

Download NVM for Windows

When you go to the official NVM download page, you’ll notice that there are many versions of nvm-windows available. Beginners often get confused about which version to download, so I suggest downloading the latest NVM version or an older one based on your project’s needs.

In most cases, the latest version works fine. Download the latest version 1.2.2 from GitHub. In my case, I had a special requirement, so Im downloading the nvm version 1.1.12 from GitHub.

Note: Before installing NVM for Windows, uninstall any existing Node.js versions, as they may conflict with Node.js versions managed by NVM.

1. Once you click the link above, a zip file named nvm-setup is downloaded to your local system, either to the Downloads folder or to any other folder you choose. Unzip that one, and within that, you will see nvm-setup as below.

2. Click nvm-setup; it will open a wizard to allow NVM into your system. Click Yes. Then, the following image will appear. I chose the I accept the agreement option and clicked the Next button.

3. Select the installation location by clicking Browse, and then click Next.

4. Select the directory for the installation of Node.js. Then click on Next.

5. This is for email subscription notifications, which can be completely disabled. You can check all options and click Next.

6. Provide your email for subscriptions. This is optional; you can leave it blank.

7. Click Install if you’re ok with the Destination location; if not, go back and change it.

8. This installs the nvm into your system. Once it is installed, open the command prompt and run the command below to check the nvm version.

nvm --version

If the nvm version number is displayed, the installation was successful.

9. To see all available Node.js versions that you can install using nvm, run the command below.

nvm list available

In the image below, you can see the list of available Node.js versions that you can download with nvm.

Let’s see how to install Node.js using Node Version Manager in the section below.

Commands to Install & Uninstall Node.js

To install a specific version of Node.js using nvm, run the following command.

nvm install <version>

Here, inplace of version, please specify the version number, for example, as below:

nvm install 22.21.1

If you want to install the latest version, then run the command below.

nvm install --lts

To see all the Node.js versions installed in your system, run the command below.

nvm list

To uninstall the Node.js version.

nvm uninstall <version>

Switching Node.js Versions

Run the command below to switch to the specific Node.js version.

nvm use <version>

Specify the version number inplace of <version>, for example:

nvm use 0.10.48

To check the currently active Node.js version, run the command below.

nvm current

Working with NPM

When we switch Node.js versions using Node Version Manager, npm is also switched to the version bundled with that Node.js version. So, to make a package available across all Node.js versions, we need to reinstall it for each version. Here is the command.

npm install -g <package-name>

In the example below, I showed how to reinstall the Gulp, Yeoman, and SharePoint Generator packages after switching Node.js versions. Running this command is mandatory; otherwise, your gulp commands, such as build, serve, package, and yo @microsoft/sharepoint, etc., won’t work.

npm install -g gulp-cli
npm install -g yo
npm install -g @microsoft/generator-sharepoint

Error: Unable to install npm on older Node.js versions 

If you installed the NVM latest version and are trying to install the very old versions of Node.js, you might face the following error.

error installing 0.10.48: open C:\users\<username>\AppDate\Local\Temp\nvm-npm-978772599\npm-v2.15.1.zip: The system cannot find the file specified.

This basically means NVM was unable to download the old npm file for that Node version. Some of the new NVM releases no longer support installing such very old Node.js versions, so the command fails.

After trying a few options and searching GitHub Issue threads, I found that NVM version 1.1.12 still supports installing older Node.js versions, such as 0.10.x and 4.x, etc. So I downloaded and installed the NVM 1.1.12, and everything worked perfectly.

• I was able to install Node.js 0.10.48 and later.
• I was also able to install newer Node.js versions(16,18,20, etc)
• Switching between them works without any issues.

Even though NVM 1.1.12 is not the latest version, it is more stable for working with very old Node versions.

Conclusion

I hope you found this tutorial helpful! If you’re working with multiple versions of SPFx and Node.js on the same computer, then follow this article and use NVM to switch between the Node.js versions, without uninstalling and reinstalling.

In this tutorial, I explained what NVM is, how to download it, the basic commands for installing and uninstalling Node.js, how to switch between Node.js versions, how to work with npm, and how to resolve errors when installing very old Node.js versions.

Also, look at some SPFx blog posts below:

• Delete node_modules from SPFx solution (rimraf)
• a ‘primitive value’ or ‘StartObject’node was expected
• Create a SharePoint List or Library Using No Framework in SPFx Web Part
• SPFx CRUD Operations using No JavaScript Framework
• Send Email in SPFx using Microsoft Graph API and PnP JS

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

The good news? SPFx gives you multiple ways to do this. In this tutorial, I’ll walk you through three practical methods with real code so you can pick the one that fits your scenario.

Here’s what we’ll cover:

• Method 1 — Fluent UI <Modal> component (best for web parts)
• Method 2 — Fluent UI <Dialog> component (great for confirmations)
• Method 3 — BaseDialog from @microsoft/sp-dialog (best for extensions)
• Method 4 — Using Native HTML <dialog> Element

Prerequisites

Before we start, make sure you have:

• Node.js (v18.x recommended for SPFx 1.18+)
• SPFx Yeoman generator installed (@microsoft/generator-sharepoint)
• A React-based SPFx solution scaffolded and ready
• Basic familiarity with TypeScript and React hooks

If you haven’t scaffolded a solution yet, run:

yo @microsoft/sharepoint

Choose WebPart, React framework, and give it a name like ModalDemo.

“Modal” vs “Dialog” in SPFx

People often use these terms interchangeably, and honestly, in everyday SPFx work, they mean the same thing — a pop-up that appears over the page content. Technically, a modal blocks interaction with the rest of the page, while a dialog may or may not. But for this tutorial, I’m using both terms to mean the same thing.

Create a Modal Popup in SharePoint Framework (SPFx)

Now, let us see different methods to create a modal popup in SharePoint Framework (SPFx).

Method 1: Fluent UI <Modal> Component

This is my go-to method for web parts. The <Modal> component from @fluentui/react gives you a lot of control over how your pop-up looks and behaves. It’s a proper overlay that blocks the rest of the page while it’s open.

When to use this

• You need a fully custom layout inside the pop-up
• You want to show a form, a table, or rich content
• You’re building inside a web part (not an extension)

Step 1 — Install Fluent UI (if not already installed)

In most SPFx 1.16+ projects, @fluentui/react is already available. Just double-check your package.json. If it’s missing:

npm install @fluentui/react --save

Also, install the hooks package:

npm install @fluentui/react-hooks --save

Step 2 — Build the Modal Component

Create a new file: "\src\webparts\spFxModelPoPups\components\MyModal.tsx"

import * as React from 'react';
import { Modal } from '@fluentui/react/lib/Modal';
import { PrimaryButton, DefaultButton, IconButton } from '@fluentui/react/lib/Button';
import { mergeStyleSets, FontWeights } from '@fluentui/react/lib/Styling';

const contentStyles = mergeStyleSets({
  container: {
    display: 'flex',
    flexFlow: 'column nowrap',
    alignItems: 'stretch',
    width: 500,
  },
  header: {
    flex: '1 1 auto',
    display: 'flex',
    alignItems: 'center',
    fontWeight: FontWeights.semibold,
    padding: '12px 12px 14px 24px',
    backgroundColor: '#0078d4',
    color: '#fff',
  },
  body: {
    flex: '4 4 auto',
    padding: '0 24px 24px',
    overflowY: 'hidden',
  },
  footer: {
    padding: '0 24px 24px',
    display: 'flex',
    justifyContent: 'flex-end',
    gap: '8px',
  },
});

interface IMyModalProps {
  isOpen: boolean;
  onDismiss: () => void;
}

const MyModal: React.FC<IMyModalProps> = ({ isOpen, onDismiss }) => {
  return (
    <Modal
      isOpen={isOpen}
      onDismiss={onDismiss}
      isBlocking={true}
      containerClassName={contentStyles.container}
    >
      <div className={contentStyles.header}>
        <span>Employee Details</span>
        <IconButton
          iconProps={{ iconName: 'Cancel' }}
          ariaLabel="Close popup modal"
          onClick={onDismiss}
          styles={{ root: { marginLeft: 'auto', color: '#fff' } }}
        />
      </div>
      <div className={contentStyles.body}>
        <p>Name: John Smith</p>
        <p>Department: Engineering</p>
        <p>Location: Bengaluru</p>
      </div>
      <div className={contentStyles.footer}>
        <DefaultButton text="Close" onClick={onDismiss} />
        <PrimaryButton text="Save" onClick={() => { alert('Saved!'); onDismiss(); }} />
      </div>
    </Modal>
  );
};

export default MyModal;

Step 3 — Use it in Your Main Web Part Component

Open "\src\webparts\spFxModelPoPups\components\SpFxModelPoPups.tsx" and update it:

Note: The web part name and file names in the path above may vary based on your project structure. Please adjust them accordingly to match your actual file names.

import * as React from 'react';
import { useState } from 'react';
import { PrimaryButton } from '@fluentui/react/lib/Button';
import MyModal from './MyModal';

const SpFxModelPoPups: React.FC = () => {
  const [isModalOpen, setIsModalOpen] = useState(false);

  return (
    <div style={{ padding: '20px' }}>
      <h2>Employee Directory</h2>
      <PrimaryButton text="View Details" onClick={() => setIsModalOpen(true)} />
      <MyModal
        isOpen={isModalOpen}
        onDismiss={() => setIsModalOpen(false)}
      />
    </div>
  );
};

export default SpFxModelPoPups;

That’s it for Method 1. Click the button, modal opens. Click the X or Close button, modal dismisses.

Key <Modal> Props You Should Know

Check out Bind SharePoint List Items to SPFx Fluent UI React Dropdown

Method 2: Fluent UI <Dialog> Component

If all you need is a confirm/cancel type popup in SPFx — like “Are you sure you want to delete this item?” — the <Dialog> component is cleaner and takes less code than <Modal>.

The <Dialog> component is purpose-built for quick confirmations and simple messages. It handles the layout for you: title, subtitle, buttons in the footer — all baked in.

A Real-World Example: Delete Confirmation

Here is a real world example to display a Delete confirmation message dialog box on a button click.

import * as React from 'react';
import { useState } from 'react';
import {
  Dialog,
  DialogType,
  DialogFooter,
} from '@fluentui/react/lib/Dialog';
import { PrimaryButton, DefaultButton } from '@fluentui/react/lib/Button';

const DeleteConfirmation: React.FC = () => {
  const [hideDialog, setHideDialog] = useState(true);

  const dialogContentProps = {
    type: DialogType.normal,
    title: 'Delete Item',
    subText: 'Are you sure you want to delete this item? This action cannot be undone.',
  };

  const modalProps = {
    isBlocking: true,
  };

  const handleDelete = () => {
    // your delete logic here
    console.log('Item deleted!');
    setHideDialog(true);
  };

  return (
    <div>
      <DefaultButton text="Delete Item" onClick={() => setHideDialog(false)} />
      <Dialog
        hidden={hideDialog}
        onDismiss={() => setHideDialog(true)}
        dialogContentProps={dialogContentProps}
        modalProps={modalProps}
      >
        <DialogFooter>
          <PrimaryButton onClick={handleDelete} text="Delete" />
          <DefaultButton onClick={() => setHideDialog(true)} text="Cancel" />
        </DialogFooter>
      </Dialog>
    </div>
  );
};

export default DeleteConfirmation;

Notice that <Dialog> uses hidden (the opposite of isOpen). It’s a small thing but it trips people up when switching between Dialog and Modal.

Using useBoolean for Cleaner State Management

One thing I love about the Fluent UI hooks package is useBoolean. Instead of managing useState manually for your open/close logic, you can do this:

import { useBoolean } from '@fluentui/react-hooks';

const [isDialogVisible, { setTrue: showDialog, setFalse: hideDialog }] = useBoolean(false);

Now instead of setIsDialogVisible(true) you just call showDialog(). Much more readable, especially when you have multiple dialogs on a page.

Method 3: BaseDialog from @microsoft/sp-dialog

This method is specifically for SPFx Extensions — ListView Command Sets and Application Customizers. The BaseDialog class from @microsoft/sp-dialog is designed to render dialogs outside the normal React component tree, which is exactly what you need in extensions where you don’t have a typical component hierarchy.

Important: When you scaffold a ListView Command Set, React is not included by default. So unlike web parts, you should build your dialog using vanilla DOM manipulation inside BaseDialog — no JSX, no Fluent UI imports needed.

When to use this

• You want to display selected item details in a dialog
• You’re building a ListView Command Set extension
• You need to trigger a popup from a toolbar button on a SharePoint list

Step 1 — Scaffold an Extension

yo @microsoft/sharepoint

Select:

• Extension → ListView Command Set
• Name it: TaskDialog

Step 2 — Create the Dialog File

Create src/extensions/taskDialog/TaskDialog.ts.

This file contains a class that extends BaseDialog. Instead of using React or JSX, we build the dialog content using vanilla DOM methods — document.createElement, textContent, and addEventListener. SharePoint provides this.domElement as the dialog container, and we append our built elements directly into it.

The dialog shows five fields from the selected list item: ID, Title, Created By, Created date, and Modified date. A styled Close button calls this.close() to dismiss the dialog.

In onAfterClose(), we clear this.domElement.innerHTML to clean up the DOM between openings — this is the equivalent of ReactDOM.unmountComponentAtNode in React-based dialogs.

import { BaseDialog, IDialogConfiguration } from '@microsoft/sp-dialog';

export interface IItemDetails {
  id: string;
  title: string;
  createdBy: string;
  created: string;
  modified: string;
}

export default class TaskDialog extends BaseDialog {
  public itemDetails: IItemDetails;

  constructor(itemDetails: IItemDetails) {
    super({ isBlocking: true });
    this.itemDetails = itemDetails;
  }

  public render(): void {
    const { id, title, createdBy, created, modified } = this.itemDetails;

    const container = document.createElement('div');
    container.style.cssText = 'padding:24px;min-width:420px;font-family:"Segoe UI",sans-serif;';

    const heading = document.createElement('div');
    heading.style.cssText = 'font-size:20px;font-weight:600;margin-bottom:20px;color:#323130;';
    heading.textContent = 'Item Details';

    const table = document.createElement('table');
    table.style.cssText = 'width:100%;border-collapse:collapse;';

    const rows: [string, string][] = [
      ['ID',         id],
      ['Title',      title],
      ['Created By', createdBy],
      ['Created',    created],
      ['Modified',   modified],
    ];

    rows.forEach(([label, value]) => {
      const tr = document.createElement('tr');

      const td1 = document.createElement('td');
      td1.style.cssText = 'font-weight:600;padding:10px 12px;border-bottom:1px solid #edebe9;color:#605e5c;width:40%;';
      td1.textContent = label;

      const td2 = document.createElement('td');
      td2.style.cssText = 'padding:10px 12px;border-bottom:1px solid #edebe9;color:#323130;';
      td2.textContent = value;

      tr.appendChild(td1);
      tr.appendChild(td2);
      table.appendChild(tr);
    });

    const footer = document.createElement('div');
    footer.style.cssText = 'margin-top:24px;text-align:right;';

    const closeBtn = document.createElement('button');
    closeBtn.style.cssText = 'padding:8px 20px;background-color:#0078d4;color:#fff;border:none;border-radius:2px;cursor:pointer;font-size:14px;';
    closeBtn.textContent = 'Close';
    closeBtn.addEventListener('click', () => {
      this.close().catch(() => { /* handle error */ });
    });

    footer.appendChild(closeBtn);
    container.appendChild(heading);
    container.appendChild(table);
    container.appendChild(footer);

    this.domElement.appendChild(container);
  }

  public getConfig(): IDialogConfiguration {
    return { isBlocking: true };
  }

  protected onAfterClose(): void {
    super.onAfterClose();
    this.domElement.innerHTML = '';
  }
}

Step 3 — Trigger It from Your Command Set

In TaskDialogCommandSet.ts, we import TaskDialog and wire it to COMMAND_1. The command stays hidden by default and only becomes visible when exactly one row is selected — handled inside _onListViewStateChanged.

When clicked, we read the selected row’s field values using getValueByName(). The Author field is a person field — SPFx returns it as an array of objects, so we extract the title property from the first element.

import { Log } from '@microsoft/sp-core-library';
import {
  BaseListViewCommandSet,
  type Command,
  type IListViewCommandSetExecuteEventParameters,
  type ListViewStateChangedEventArgs
} from '@microsoft/sp-listview-extensibility';
import TaskDialog from './TaskDialog';

export interface ITaskDialogCommandSetProperties {
  sampleTextOne: string;
}

const LOG_SOURCE: string = 'TaskDialogCommandSet';

export default class TaskDialogCommandSet extends BaseListViewCommandSet<ITaskDialogCommandSetProperties> {

  public onInit(): Promise<void> {
    Log.info(LOG_SOURCE, 'Initialized TaskDialogCommandSet');

    const viewDetailsCommand: Command = this.tryGetCommand('COMMAND_1');
    viewDetailsCommand.visible = false;

    this.context.listView.listViewStateChangedEvent.add(this, this._onListViewStateChanged);

    return Promise.resolve();
  }

  public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
    switch (event.itemId) {
      case 'COMMAND_1': {
        const row = event.selectedRows[0];

        const id       = String(row.getValueByName('ID') || '');
        const title    = String(row.getValueByName('Title') || '');
        const created  = new Date(row.getValueByName('Created')  as string).toLocaleString();
        const modified = new Date(row.getValueByName('Modified') as string).toLocaleString();

        // Author is a person field — SPFx returns an array of objects with a title property
        const authorRaw = row.getValueByName('Author');
        let createdBy = '';
        if (Array.isArray(authorRaw) && authorRaw.length > 0) {
          const first = authorRaw[0];
          createdBy = typeof first === 'object' && first !== null
            ? String((first as { title?: string; Title?: string }).title || (first as { title?: string; Title?: string }).Title || first)
            : String(first);
        }

        const dialog = new TaskDialog({ id, title, createdBy, created, modified });
        dialog.show().catch((err) => { console.error('TaskDialog error:', err); });
        break;
      }
      default:
        throw new Error('Unknown command');
    }
  }

  private _onListViewStateChanged = (_args: ListViewStateChangedEventArgs): void => {
    Log.info(LOG_SOURCE, 'List view state changed');

    const viewDetailsCommand: Command = this.tryGetCommand('COMMAND_1');
    if (viewDetailsCommand) {
      // Show only when exactly one row is selected
      viewDetailsCommand.visible = this.context.listView.selectedRows?.length === 1;
    }

    this.raiseOnChange();
  }
}

Manifest file (TaskDialogCommandSet.manifest.json)

Only COMMAND_1 is defined. The title is set to “View Details” so the toolbar button is meaningful to the user.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/command-set-extension-manifest.schema.json",
  "id": "0465f20d-8ea6-4117-9e72-4924124472e1",
  "alias": "TaskDialogCommandSet",
  "componentType": "Extension",
  "extensionType": "ListViewCommandSet",
  "version": "*",
  "manifestVersion": 2,
  "requiresCustomScript": false,
  "items": {
    "COMMAND_1": {
      "title": { "default": "View Details" },
      "iconImageUrl": "icons/request.png",
      "type": "command"
    }
  }
}

Important: Always clean up the DOM

Always clear this.domElement.innerHTML in onAfterClose(). If you skip this, the previous dialog content remains in the DOM, and you’ll see stale or duplicated data the next time the dialog is opened.

Method 4: Native HTML <dialog> Element

This one’s worth knowing about. Modern browsers have a built-in <dialog> HTML element that works perfectly fine in SPFx. No Fluent UI needed. No extra packages. Just plain HTML and TypeScript.

It’s a bit more of a “do it yourself” approach, but it’s lightweight, and it works well for non-React web parts.

export default class NativeDialogWebPart extends BaseClientSideWebPart<{}> {
  private _dialog: HTMLDialogElement;

  public render(): void {
    this.domElement.innerHTML = `
      <div>
        <button id="openBtn">Open Dialog</button>
        <dialog id="myDialog">
          <h2>Hello from a native dialog!</h2>
          <p>This is a lightweight modal using the HTML dialog element.</p>
          <button id="closeBtn">Close</button>
        </dialog>
      </div>
    `;

    this._dialog = this.domElement.querySelector('#myDialog') as HTMLDialogElement;

    this.domElement.querySelector('#openBtn')!.addEventListener('click', () => {
      (this._dialog as any).showModal();
    });

    this.domElement.querySelector('#closeBtn')!.addEventListener('click', () => {
      this._dialog.close();
    });
  }
}

One heads-up: TypeScript’s type definitions in SPFx don’t always recognize the showModal() method on the HTMLDialogElement, so you may need to cast it to any like I did above. It’s a known limitation in the SPFx TypeScript setup, not a bug in your code.

Which Method Should You Pick?

Here’s a simple way to think about it:

• Building a web part? → Use Fluent UI <Modal> (Method 1) for complex UIs, or <Dialog> (Method 2) for confirmations
• Building a ListView Command Set extension? → Use BaseDialog (Method 3)
• Want something ultra-lightweight with no extra packages? → Native HTML <dialog> (Method 4)
• Need clean state management code? → Combine any React method with useBoolean from @fluentui/react-hooks

Common Issues and How to Fix Them

Here are some common issues that I faced and the fixes

Testing Your Modal Popup in SPFx

Run your solution locally:

gulp serve

For web parts, it opens your local workbench at https://tenantname.sharepoint.com/sites/sitename/_layouts/15/workbench.aspx. For extensions, update the pageUrl in config/serve.json to point to an actual SharePoint list URL in your tenant.

When prompted in the browser, click Load debug scripts to allow your local code to run on the SharePoint page.

Download SPFx Modal Popup Solution

Click the button below to download the SPFx solution packages for all examples covered in this post, plus access to 100+ additional solutions.

Wrapping Up

In this tutorial, I explained various methods to create modal popups in SharePoint Framework (SPFx). For most web part scenarios, the Fluent UI <Modal> or <Dialog> component is all you need. For extensions, BaseDialog it gives you the right structure.

The key thing to remember is that Fluent UI keeps things consistent with the SharePoint UI. Your modal will look and feel native to SharePoint rather than like something bolted on.

Also, you may like:

• SharePoint Framework (SPFx) Fluent UI Basic List Example
• Fluent UI DocumentCard in SPFx Web Part
• Build a Custom Slides Manager in SPFx Web Part Property Pane (Drag & Drop, Reorder, Hide Slides)
• SPFx SwatchColorPicker Office UI Fabric React Control example

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

By the end, you will have an SPFx client-side web part where the dropdown is dynamically populated from a SharePoint list and always stays in sync with the items in that list.

Prerequisites and Scenario

In this example, a SharePoint list named Product is used, with the columns: Title (Single line of text) and ProductName (Single line of text). Here is the SharePoint list in the screenshot below:

The goal is to fetch items from this Product list using PnP JS and bind them to a Fluent UI React dropdown in an SPFx web part. The output will come like the screenshot below:

Check out Display SharePoint List Items in SPFx Web Part

Create the SPFx React Web Part

1. Open Node.js command prompt and create a folder, then go inside it:

mkdir ProductDropdown
cd ProductDropdown

2. Run the SharePoint Framework Yeoman generator:

yo @microsoft/sharepoint

3. Answer the prompts (example values):
   • Solution name: product-dropdown
   • Which type of client-side component to create?: WebPart
   • Web part name: ProductDropdown
   • Which template would you like to use?: React

The generator will install all dependencies and scaffold the SPFx project.

Install Fluent UI and PnP JS

After project creation, install the required libraries.

• Fluent UI React:

npm install @fluentui/react

• PnP JS (sp-pnp-js):

npm install sp-pnp-js

Then open the project in VS Code:

Code .

You can see the project structure on the left side of the code editor(VS Code editor).

Check out Build a SharePoint Folder Tree View Using SharePoint Framework (SPFx)

Create Interfaces and Classes for List Items

Navigate to src\webparts\productDropdown\components.

1. Create the interface file IProducts.ts

First, create an interface like below. This interface defines the shape of each SharePoint list item returned by PnP JS, mapping the Id, Title, and ProductName fields.

export interface ISPListProductItem{
    Id:any;
    Title:string;
    ProductName:string;
  }

2. Create the class file ClassProduct.ts

This class takes a raw SharePoint list item and exposes only the properties we need — Id and ProductName — to keep the dropdown logic clean and simple.

import { ISPListProductItem } from "./IProducts";

export class  ClassProduct{
    public ProductName:string;
    public Id:any
    constructor(item: ISPListProductItem) {
      this.ProductName = item.ProductName;
      this.Id=item.Id

  }
}

This class wraps each SharePoint list item and exposes ProductName and Id that will be used in the dropdown options.

Implement the Fluent UI Dropdown in ProductDropdown.tsx

Open src\webparts\productDropdown\components\ProductDropdown.tsx.

1. Import required modules

Import PnP JS to fetch SharePoint list data, the ClassProduct class we created, and the Fluent UI Dropdown component along with its types.

import * as React from 'react';
import styles from './ProductDropdown.module.scss';
import { IProductDropdownProps } from './IProductDropdownProps';
import pnp from 'sp-pnp-js'
import { ClassProduct } from './ClassProduct';
// import { ISPListProductItem } from './IProducts';
import {Dropdown, IDropdownOption} from '@fluentui/react';

2. Define the component state

The state holds the list of dropdown options fetched from SharePoint and tracks the currently selected item.

export interface IProductDropdownState {
  selectedProduct?: IDropdownOption;
  items: IDropdownOption[];
}

3. Create the React component with constructor

The constructor initializes the component state with an empty items array and no selected product, which will be populated once the component mounts.

export default class ProductDropdown extends React.Component<IProductDropdownProps, IProductDropdownState> {
  constructor(props: IProductDropdownProps) {
    super(props);
    this.state = {
      selectedProduct: undefined,
      items: []
    };
  }

4. Render the Fluent UI dropdown and load data

The render method displays the Fluent UI dropdown, componentDidMount triggers the SharePoint data fetch, and _getListProductData maps list items into dropdown options and updates the state.

Use the following full code in ProductDropdown.tsx:

export default class ProductDropdown extends React.Component<IProductDropdownProps, IProductDropdownState> {
  constructor(props: IProductDropdownProps) {
    super(props);
    this.state = {
      selectedProduct: undefined,
      items: []
    };
  }

  public render(): React.ReactElement<IProductDropdownProps> {
    return (
      <section className={`${styles.productDropdown}`}>
        <Dropdown
          label="Select a product"
          options={this.state.items}
          selectedKey={this.state.selectedProduct?.key}
          onChange={this.onDropdownChange}
        />
      </section>
    );
  }

  public componentDidMount(){
    this._getListProductData();
  }

  private _getListProductData() : void {
    pnp.sp.web.lists.getByTitle(`Product`).items.get().then((response: any) => {
      let productCollection = response.map((item: any) => new ClassProduct(item));
      let dropdownOptions = productCollection.map((product: ClassProduct) => {
        return {
          key: product.Id,
          text: product.ProductName
        };
      });
      this.setState({ items: dropdownOptions });
    });
  }

  private onDropdownChange = (event: React.FormEvent<HTMLDivElement>, item: IDropdownOption): void => {
    this.setState({ selectedProduct: item });
  }
}

This code loads items from the Product list in componentDidMount, maps them to dropdown options, and binds them to the Fluent UI dropdown.

Check out SharePoint Framework (SPFx) Interview Questions and Answers

Update the Web Part Entry File

Open src\webparts\productDropdown\ProductDropdownWebPart.ts and use this code:

import * as React from 'react';
import * as ReactDom from 'react-dom';
import { Version } from '@microsoft/sp-core-library';
import {
  IPropertyPaneConfiguration,
  PropertyPaneTextField
} from '@microsoft/sp-property-pane';
import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';

import * as strings from 'ProductDropdownWebPartStrings';
import ProductDropdown from './components/ProductDropdown';
import { IProductDropdownProps } from './components/IProductDropdownProps';

export interface IProductDropdownWebPartProps {
  description: string;
}

export default class ProductDropdownWebPart extends BaseClientSideWebPart<IProductDropdownWebPartProps> {

  public async render(): Promise <void> {
    const element: React.ReactElement<IProductDropdownProps> = React.createElement(
      ProductDropdown,
    );

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

  protected onDispose(): void {
    ReactDom.unmountComponentAtNode(this.domElement);
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }

  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: {
            description: strings.PropertyPaneDescription
          },
          groups: [
            {
              groupName: strings.BasicGroupName,
              groupFields: [
                PropertyPaneTextField('description', {
                  label: strings.DescriptionFieldLabel
                })
              ]
            }
          ]
        }
      ]
    };
  }
}

This wires the React component into the SPFx web part and keeps a simple property pane.

Configure Gulp Serve URL and Test the Web Part

1. Open config\serve.json and set your SharePoint site URL in the pageUrl property so the local workbench loads against your site; like the below screenshot:

2. Start the local server: gulp serve
3. In the modern workbench, add the ProductDropdown web part to the page.
4. Click the dropdown to see all ProductName values from the Product list; any new items you add to the list will automatically appear in the dropdown.

Download the Complete SPFx Solution

You can download the full solution as a zip file and run it locally.

• Download:
  https://www.spguides.com/wp-content/uploads/2023/04/bind-the-SharePoint-list-item-in-the-Spfx-webpart-dropdown.zip

After unzipping, install dependencies:

npm i

Wrap-up

This tutorial walked through creating an SPFx React web part that reads items from a SharePoint list using PnP JS and binds them to a Fluent UI dropdown. You now have a reusable pattern for populating dropdowns from SharePoint lists, and any new items in the list will automatically appear to users in the web part.

You may also like the following tutorials:

• Build a Custom Slides Manager in SPFx Web Part Property Pane (Drag & Drop, Reorder, Hide Slides)
• SPFX SwatchColorPicker Fluent UI React Control
• Fluent UI DocumentCard in SPFx Web Part
• SharePoint Framework (SPFx) Fluent UI Basic List Example

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

Here, the client was required to track guest users who download any file from the document library by sending an email to the authorised person notifying them that someone had downloaded the file.

But in the SharePoint library command bar, the “Download” option doesn’t automatically include the option to send emails and notifications. So, after researching, we found a way to customise the default “Download” button using the SPFx list view command set extension.

In this article, I will explain how to customize SharePoint list command bar download button to send an email using SharePoint Framework (SPFx).

Customize SharePoint List Download Button to Send Emails Using SPFx Extension

In the SharePoint framework, with the list view command set extension, we can customize the SharePoint list command bars and context menu buttons by adding custom buttons based on our requirements.

But here, we need to modify the existing [Download] button functionality, such as sending an email to an authorised person to notify them that the file has been downloaded by this person.

Get Unique Identifier for SharePoint List Command Bar Buttons

To do this, we first need to find the unique identifier of that “Download” button. Follow the steps below to identify the unique identifier.

1. Open the SharePoint document library -> Select one or two files, and then in the command bar, or in the context menu, you’ll see the “Download” button.
2. Then, click on the [Ctrl + Shift + I] keys at the same time on the keyboard. Otherwise, right-click and a pop-up will come; click on the inspect option.

2. Then, it will open the inspection page and click the 1st icon in the top toolbar on the right side pane. Then, keep your cursor on the “Download” button and click on it. You will find the button code on the right side. Now you can see the “downloadCommand” as the ID for that button, and copy it.

Now, we need to implement the functionality to send emails when we click this button. Let’s see how to do that in the section below!

Create SPFx List View Command Set Extension

Follow the steps below to create a SharePoint framework list view command set extension. This extension is using the Microsoft Graph to send emails. With MSGraph, we can send emails to both internal and external users.

1. Open the command prompt and run the commands below to create a solution.

md SPFxListViewExtDownload

cd SPFxListViewExtDownload

2. Then run the command below to scaffold our spfx solution.

yo @microsoft/sharepoint

3. This will prompt you with the following questions. Answer them as I gave below.

• What is your solution name? SPFxListViewExtDownload
• Which type of client-side component to create? Extension
• Which type of client-side extension to create? ListView Command Set
• Add new Command Set to solution sp-fx-list-view-ext-download.
• What is your Command Set name? custDownload

4. Once the solution is created successfully, open the “package-solution.json” located in the config folder. Then add the code below as shown.

"webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Mail.Send"
      }
    ]

In this code, we are adding permission to send emails, so we need to get approval for this permission from the admin team in the “SharePoint Admin Centre” under “API access”. Otherwise, the email won’t be sent to the user mentioned in the code.

5. Then open the “CustDownloadCommandSet.ts” file in the src folder and replace the default code with the code below.

import { Log } from '@microsoft/sp-core-library';
import {
  BaseListViewCommandSet,
  type Command,
  type IListViewCommandSetExecuteEventParameters,
  type ListViewStateChangedEventArgs
} from '@microsoft/sp-listview-extensibility';
import { MSGraphClientV3 } from '@microsoft/sp-http';

export interface ICustDownloadCommandSetProperties {
  // This is an example; replace with your own properties
  sampleTextOne: string;
  sampleTextTwo: string;
}

const LOG_SOURCE: string = 'CustDownloadCommandSet';
const EMAIL_RECIPIENT: string = 'Provie your email address'; 

export default class CustDownloadCommandSet extends BaseListViewCommandSet<ICustDownloadCommandSetProperties> {

  public onInit(): Promise<void> {
    Log.info(LOG_SOURCE, 'Initialized CustDownloadCommandSet');

    // initial state of the command's visibility
    const compareOneCommand: Command = this.tryGetCommand('COMMAND_1');
    compareOneCommand.visible = false;
    this.context.listView.listViewStateChangedEvent.add(this, this._onListViewStateChanged);
   
    this._attachDownloadClickHandler();
    return Promise.resolve();
  }

  public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
    switch (event.itemId) {
      case 'COMMAND_1':
        break;
      case 'COMMAND_2':
        break;
      default:
        throw new Error('Unknown command');
    }
  }

  private _onListViewStateChanged = (args: ListViewStateChangedEventArgs): void => {
    Log.info(LOG_SOURCE, 'List view state changed');

    const compareOneCommand: Command = this.tryGetCommand('COMMAND_1');
    const comparetwoCommand: Command = this.tryGetCommand('COMMAND_2');
    if (compareOneCommand) {
      // This command should be hidden unless exactly one row is selected.
      compareOneCommand.visible = this.context.listView.selectedRows?.length === 1;
    }
    if (comparetwoCommand) {
      comparetwoCommand.visible = false;
    }
    // TODO: Add your logic here

    // You should call this.raiseOnChage() to update the command bar
    this.raiseOnChange();
  }

  //Attaches a click listener to the existing default "Download"button.

private _attachDownloadClickHandler(): void {
  const attachHandler = () => {
    const downloadButton = document.querySelector('button[data-automationid="downloadCommand"]') as HTMLElement;
    if (downloadButton && !downloadButton.getAttribute('listener-attached')) {
      downloadButton.setAttribute('listener-attached', 'true');
      downloadButton.addEventListener('click', this._onDownloadClicked.bind(this));
      console.log('%cDownload button listener attached (current instance)', 'color: green');
    }
  };

  // Initial attempt
  attachHandler();

  // Watch for DOM changes in the toolbar or context menu area
  const observer = new MutationObserver(() => {
    attachHandler(); // reattach when DOM changes
  });

  observer.observe(document.body, {
    childList: true,
    subtree: true
  });

  console.log('%cWatching for Download button re-render...', 'color: orange');
}
//Executes when the built-in Download button is clicked.
private _onDownloadClicked(): void {
    try {
      const selectedRows = this.context.listView.selectedRows;
      if (selectedRows && selectedRows.length > 0) {
        const fileNames = selectedRows.map((r: any) => r.getValueByName('FileLeafRef'));
        const user = this.context.pageContext.user.displayName;

        alert(`${user} downloaded: ${fileNames.join(', ')}`);

        this._sendDownloadEmail(fileNames, user);
      }
    } catch (err) {
      console.error("Error handling Download click:", err);
    }
  }
    //Sends an email notification via MS Graph when files are downloaded.    
private _sendDownloadEmail(fileNames: string[], user: string): void {
  console.log('Preparing to send email through MSGraphClientV3...');
  this.context.msGraphClientFactory
    .getClient('3')
    .then((client: MSGraphClientV3) => {
      const siteUrl = this.context.pageContext.web.absoluteUrl;
      const siteName = this.context.pageContext.web.title;
      const emailBody = `
        <div style="font-family:Segoe UI, Arial, sans-serif; font-size:14px; color:#333;">
          <p>Hi <strong>Bijay</strong>,</p>
          
          <p>This is to inform you that <strong>${user}</strong> has downloaded the following file(s) from the SharePoint site 
          <a href="${siteUrl}" style="color:#0078D4; text-decoration:none;">${siteName}</a>:</p>

          <ul style="margin-top:8px; margin-bottom:8px;">
            ${fileNames.map(f => `<li>${f}</li>`).join('')}
          </ul>

          <p style="margin-top:16px;">Best regards,<br>
          <strong>SharePoint System</strong></p>
        </div>
      `;

      const email = {
        message: {
          subject: `File Download Notification - ${user}`,
          body: {
            contentType: 'HTML',
            content: emailBody
          },
          toRecipients: [
            {
              emailAddress: { address: EMAIL_RECIPIENT }
            }
          ]
        },
        saveToSentItems: false
      };

      client.api('/me/sendMail').post(email)
        .then(() => console.log('Email sent successfully to', EMAIL_RECIPIENT))
        .catch(err => console.error('Error sending email:', err));
    })
    .catch(err => console.error('Error initializing MSGraphClientV3:', err));
}
}

• At the start, we imported the MSGraphClientV3 from the @microsoft/sp-http to send emails.
• const EMAIL_RECIPIENT: string = ‘Provie your email address’ = This variable holds the user email adrress.
• this._attachDownloadClickHandler(); = We called the function in the OnInit method, which attaches the handler to the default “Download” button.
• onExecute() = This is the default code that runs when a custom button is clicked, but since we are not adding any custom buttons, no action will be performed.
• _onListViewStateChanged() = The default function that runs when changes occur in the SharePoint list or document library. Here, we are adding the visibility logic for the custom buttons. Since we are not using the custom buttons, I set both to a false value, so they won’t be visible when something happens in the list view.
• _attachDownloadClickHandler() = This function will perform the following actions:
  • Detect the default “Download” button rendered by SharePoint using the code below:
  • const downloadButton = document.querySelector(‘button[data-automationid=”downloadCommand”]‘) as HTMLElement;
  • Attach a custom event handler to it without modifying the page directly.
  • And keep reattaching it whenever SharePoint re-renders the toolbar.
• _onDownloadClicked() = This method is a custom event handler that runs when the default SharePoint “Download” button is clicked, the one attached using the previous function.
  • It will detect which files the user is downloading and then run custom logic, such as showing an alert and sending an email.
• _sendDownloadEmail(fileNames: string[], user: string) = In this function we called the _onDownloadClicked() after detecing a file downloaded.
  • This function takes the downloaded file names and the user name who downloaded them as input and does not return anything.
  • this.context.msGraphClientFactory.getClient(‘3’).then((client: MSGraphClientV3) => {..} allows us to connect to Microsoft Graph to access APIs such as Outlook, Users, Groups, and more.
  • We are using the vGraph client version 3.
  • Then we fetched the siteUrl and siteName from the context and prepared the email body.
  • Sent email using the MSGraph ‘/me/sendMail’ API.

6. To test this extension locally, open the serve.json file located in the config folder. There, you can see the “pageUrl” as given below.

https://{tenantDomain}/SitePages/myPage.aspx

Update that with your SharePoint library URL, like below.

"https://szg52.sharepoint.com/sites/SPFXDevelopment/HRDocuments/Forms/AllItems.aspx"

7. Once it’s over, run the below command either in the command prompt or in the Terminal pane.

gulp serve

8. Now, as shown below, click Load debug scripts, select the files in the library, and click the “Download” button. You’ll see an alert, and then you’ll receive an email.

That’s it, this way we can easily customise the existing command buttons in the SharePoint list or library using the SPFx list view command set extension.

I hope you found this article helpful!, Here, I have explained how to access the default buttons in a SharePoint list or library command bar, context menu, and customize them using the SharePoint framework list view command set extension.

I will recomended, download this solution and try it once. In the comments, let me know if you run into any issues and share your feedback on this tutorial.

You may also like the following SPFx tutorials:

• SharePoint Framework User Profile Web Part [Using MS Graph API]
• Get Current SharePoint Site Information in SPFx using MS Graph API
• Create a SharePoint List using SharePoint Framework [Including Adding Columns]
• Create Folders and Subfolders in SharePoint document library using SPFx
• SPFx Application Customizer Example

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

While implementing this solution, I followed a clean approach where the SPFx form uploads the file and updates the document metadata in a single step.

In this tutorial, I will explain how to upload files to a SharePoint document library and update metadata using SPFx.

Upload File to SharePoint Document Library With Metadata in SPF Client Side WebPart

In the image below, you can see the SharePoint document library named “USA Citizenship,” which stores the files and their metadata.

This library has the following fields:

Here is the SPFx web part that renders the complete citizenship form. It includes all required metadata fields, a file upload control for attaching identity documents, and Submit/Reset buttons to submit the form and clear the data.

Now, we’ll see how to create this form in the SPFx web part and submit the input data to the SharePoint document library. We will use the PnPJS library to interact with SharePoint.

I hope by this time, you know how to create SPFx web part using React, and in case you’re new to SPFx, you can check how to set up an SPFx development environment.

1. Run the command below to install the PnPJS library into our solution.

npm install @pnp/sp --save

2. Open the .ts file and add the following imports and PnPJS setup into the existing code.

import { spfi, SPFx } from "@pnp/sp";
import { SPFI } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/lists";
import "@pnp/sp/items";
import "@pnp/sp/fields";
import "@pnp/sp/folders";
import "@pnp/sp/files";
import "@pnp/sp/files/web";
export interface IUsaCitizenshipFormWebPartProps {
  description: string;
}

export default class UsaCitizenshipFormWebPart extends BaseClientSideWebPart<IUsaCitizenshipFormWebPartProps> {

  private _isDarkTheme: boolean = false;
  private _environmentMessage: string = '';
  private _sp: SPFI

  public render(): void {
    const element: React.ReactElement<IUsaCitizenshipFormProps> = React.createElement(
      UsaCitizenshipForm,
      {
        description: this.properties.description,
        isDarkTheme: this._isDarkTheme,
        environmentMessage: this._environmentMessage,
        hasTeamsContext: !!this.context.sdks.microsoftTeams,
        userDisplayName: this.context.pageContext.user.displayName,
        sp:this._sp,
        context:this.context,
      }
    );

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

  protected onInit(): Promise<void> {
    return this._getEnvironmentMessage().then(message => {
      this._environmentMessage = message;
      this._sp = spfi().using(SPFx(this.context));
    });
  }

Here:

• We imported the PnPJS library statements required to interact with SharePoint.
• Initialized a variable _sp to hold the PnPJs instance.
• In the onInit() method, I created the PnPJs instance, and in the render() method, I assigned that instance to the prop sp.

3. Also, update the Props.ts file code with the code below.

import { WebPartContext } from "@microsoft/sp-webpart-base";
import { SPFI } from "@pnp/sp";
export interface IUsaCitizenshipFormProps {
  description: string;
  isDarkTheme: boolean;
  environmentMessage: string;
  hasTeamsContext: boolean;
  userDisplayName: string;
  sp:SPFI;
  context: WebPartContext
}

Here, we also added the sp and context props to the existing props.

4. Now open the .tsx file and replace your default code with the code below.

import * as React from "react";
import type { IUsaCitizenshipFormProps } from "./IUsaCitizenshipFormProps";
import styles from "./UsaCitizenshipForm.module.scss";

export interface IUsaCitizenshipFormState {
  CurrentLegalName: string;
  NameExactlyOnYourPRC: string;
  DOB: string;
  MaritalStatus: string;
  Disability: string[];
  CountryOfNationality: string;
  CountryOfBirth: string;
  Emailid: string;
  Contact: string;
  Gender: string;
  file: File | null;
  statusMessage: string;
  errors: string[];
  isSubmitting: boolean;
  statusType: "success" | "error" | "";
}

export default class UsaCitizenshipForm extends React.Component<
  IUsaCitizenshipFormProps,
  IUsaCitizenshipFormState
> {
  constructor(props: IUsaCitizenshipFormProps) {
    super(props);


    this.state = {
      CurrentLegalName: "",
      NameExactlyOnYourPRC: "",
      DOB: "",
      MaritalStatus: "",
      Disability: [],
      CountryOfNationality: "",
      CountryOfBirth: "",
      Emailid: "",
      Contact: "",
      Gender: "",
      file: null,
      statusMessage: "",
      errors: [],
      isSubmitting: false,
      statusType:""
    };
  }


  private handleInputChange = (
    e: React.ChangeEvent<HTMLInputElement | HTMLSelectElement>
  ) => {
    this.setState({ [e.target.name]: e.target.value } as any);
  };

  private handleMultiSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
    const { value, checked } = e.target;
    let selected = [...this.state.Disability];

    if (checked) {
      if (!selected.includes(value)) selected.push(value);
    } else {
      selected = selected.filter((v) => v !== value);
    }

    this.setState({ Disability: selected });
  };

  private handleFileSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
    this.setState({ file: e.target.files ? e.target.files[0] : null });
  };

  private validateForm = (): boolean => {
    let errors: string[] = [];

    if (!this.state.CurrentLegalName.trim())
      errors.push("Current Legal Name is required.");

    if (!this.state.CountryOfNationality.trim())
      errors.push("Country of Nationality is required.");

    if (!this.state.CountryOfBirth.trim())
      errors.push("Country of Birth is required.");

    if (!this.state.Gender.trim())
      errors.push("Gender is required.");

    if (!this.state.file)
      errors.push("Identity Proof file must be uploaded.");

    this.setState({ errors });
    return errors.length === 0;
  };
private uploadFormData = async () => {
  if (!this.validateForm()) {
    this.setState({ 
      statusMessage: "Please fill the mandatory fields",
      statusType: "error"
    });
    return;
  }

  this.setState({ statusMessage: "Submitting...", isSubmitting: true, statusType: "" });

  try {
    const sp = this.props.sp;
    const libraryPath = "/sites/SPFXDevelopment/USACitizenship";
    const file = this.state.file;

    if (!file) {
      this.setState({ statusMessage: "Please select a file.", statusType: "error", isSubmitting: false });
      return;
    }

    const folder = sp.web.getFolderByServerRelativePath(libraryPath);
    await folder.files.addUsingPath(file.name, file, { Overwrite: true });

    const filePath = `${libraryPath}/${file.name}`;
    const spFile = sp.web.getFileByServerRelativePath(filePath);
    const item = await spFile.getItem();

    await item.update({
      Title: this.state.CurrentLegalName,
      CurrentLegalName: this.state.CurrentLegalName,
      NameExactlyOnYourPRC: this.state.NameExactlyOnYourPRC,
      DOB: this.state.DOB,
      MaritalStatus: this.state.MaritalStatus,
      Disability: this.state.Disability,
      CountryOfNationality: this.state.CountryOfNationality,
      CountryOfBirth: this.state.CountryOfBirth,
      Emailid: this.state.Emailid,
      Contact: this.state.Contact,
      Gender: this.state.Gender
    });

    this.setState({ statusMessage: "Form submitted successfully!", statusType: "success", isSubmitting: false });
  } catch (err: any) {
    this.setState({ statusMessage: "Error: " + err.message, statusType: "error", isSubmitting: false });
  }
};
private resetForm = () => {
  this.setState({
    CurrentLegalName: "",
    NameExactlyOnYourPRC: "",
    DOB: "",
    MaritalStatus: "",
    Disability: [],
    CountryOfNationality: "",
    CountryOfBirth: "",
    Emailid: "",
    Contact: "",
    Gender: "",
    file: null,
    statusMessage: "",
    errors: [],
    isSubmitting: false,
    statusType: ""
  });
};

  public render() {
    return (
      <div className={styles.formContainer}>

        <h2 className={styles.formTitle}>Citizenship Form</h2>


        <label>Current Legal Name<span style={{ color: "red" }}>*</span></label>
        <input
          type="text"
          name="CurrentLegalName"
          className={styles.input}
          value={this.state.CurrentLegalName}
          onChange={this.handleInputChange}
        />


        <label>Name exactly as it appears on your Permanent Resident Card (PRC)</label>
        <input
          type="text"
          name="NameExactlyOnYourPRC"
          className={styles.input}
          value={this.state.NameExactlyOnYourPRC}
          onChange={this.handleInputChange}
        />
        <label>Date of Birth</label>
        <input
          type="date"
          name="DOB"
          className={styles.input}
          value={this.state.DOB}
          onChange={this.handleInputChange}
        />

        <label>Marital Status</label>
        <select
          name="MaritalStatus"
          className={styles.input}
          value={this.state.MaritalStatus}
          onChange={this.handleInputChange}
        >
          <option value="">-- Select Marital Status --</option>
          <option value="Married">Married</option>
          <option value="Single">Single</option>
          <option value="Divorced">Divorced</option>
          <option value="Widowed">Widowed</option>
        </select>


        <label>Disability Impairment:</label>

        <div className={styles.checkboxGroup}>
          <label>
            <input
              type="checkbox"
              value="I am deaf or hearing impaired and need a sign language interpreter who uses my language"
              onChange={this.handleMultiSelect}
              checked={this.state.Disability.includes(
        "I am deaf or hearing impaired and need a sign language interpreter who uses my language"
      )}
            />
            I am deaf or hearing impaired and need a sign language interpreter who uses my language
          </label>

          <label>
            <input type="checkbox" value="I use a wheelchair" onChange={this.handleMultiSelect} checked={this.state.Disability.includes("I use a wheelchair")} />
            I use a wheelchair
          </label>

          <label>
            <input
              type="checkbox"
              value="I am blind or sight impaired"
              onChange={this.handleMultiSelect}
              checked={this.state.Disability.includes("I am blind or sight impaired")}
            />
            I am blind or sight impaired
          </label>

          <label>
            <input
              type="checkbox"
              value="I will need another type of accommodation"
              onChange={this.handleMultiSelect}
              checked={this.state.Disability.includes("I will need another type of accommodation")}
            />
            I will need another type of accommodation
          </label>
        </div>

        <label>Country Of Nationality<span style={{ color: "red" }}>*</span></label>
        <input
          type="text"
          name="CountryOfNationality"
          className={styles.input}
          value={this.state.CountryOfNationality}
          onChange={this.handleInputChange}
        />


        <label>Country Of Birth<span style={{ color: "red" }}>*</span></label>
        <input
          type="text"
          name="CountryOfBirth"
          className={styles.input}
          value={this.state.CountryOfBirth}
          onChange={this.handleInputChange}
        />

        <label>Email Id</label>
        <input
          type="text"
          name="Emailid"
          className={styles.input}
          value={this.state.Emailid}
          onChange={this.handleInputChange}
        />

        <label>Contact Number</label>
        <input
          type="text"
          name="Contact"
          className={styles.input}
          value={this.state.Contact}
          onChange={this.handleInputChange}
        />

        <label>Gender</label>
        <select
          name="Gender"
          className={styles.input}
          value={this.state.Gender}
          onChange={this.handleInputChange}
        >
          <option value="">-- Select gender --</option>
          <option value="Male">Male</option>
          <option value="Female">Female</option>
          <option value="Other">Other</option>
        </select>
        <label>Upload Identity Proof</label>
        <input type="file" className={styles.input} onChange={this.handleFileSelect} />
<div style={{ marginTop: '10px' }}>
        <button
        className={styles.submitBtn}
        onClick={this.uploadFormData}
        disabled={this.state.isSubmitting}
      >
        {this.state.isSubmitting ? "Submitting..." : "Submit"}
      </button>
  <button
    className={styles.submitBtn}
    style={{ background: "#6c757d", marginLeft: "10px" }}
    onClick={this.resetForm}
    disabled={this.state.isSubmitting} 
  >
    Reset
  </button>
  </div>
       
      {this.state.statusMessage && (
        <div
          className={styles.status}
          style={{ color: this.state.statusType === "success" ? "green" : this.state.statusType === "error" ? "red" : "black" }}
        >
          {this.state.statusMessage}
        </div>
      )}
      {this.state.errors.length > 0 && (
        <div className={styles.errorBox}>
          {this.state.errors.map((err, index) => (
            <div key={index}>• {err}</div>
          ))}
        </div>
      )}
    
      </div>
    );
  }
}

Here:

• IUsaCitizenshipFormState = Created this state to hold the form input data for saving to the library. It contains all the SharePoint library fields, along with states to handle errors and change the button title.
• Within the constructor(), we initialized these states with empty values.
• Created handleInputChange() and handleMultiSelect() helper methods to update the state values when the user enters data in the form input controls.
• This handleFileSelect() method stores the selected file in the file state.
• The validateForm() method checks whether we have provided data for the mandatory fields. If not, it adds the validation messages to the state errors array.
• In the resetForm() method, we set the state values to empty, so when we click the Reset button, the form fields are cleared.
• The uploadFormData() will be triggered when we click the Submit button.
  • It first calls the validateForm() method to check whether any fields are missing data, then updates the statusMessage state so the submit button text changes to “Submitting…”
  • In the try{} block, we check whether the file exists. If yes, then we are uploading it into the “USACitizenship” document library using PnPJs. And then we retrieve that item and update its metadata.
• In the render() method, it displays the form with various input controls for the metadata, along with buttons. Down to the buttons, showing the error block so the user knows.

5. Also, add the styles to this web part by updating the CSS styles in the .scss file.

.formContainer {
  width: 70%;
  margin: auto;
  background: #f8f8f8;
  padding: 25px;
  border-radius: 6px;
  border: 1px solid #ccc;
}

.formTitle {
  text-align: center;
  margin-bottom: 20px;
  font-size: 26px;
  font-weight: bold;
}

.input {
  width: 100%;
  padding: 8px;
  margin-bottom: 12px;
  border: 1px solid #ccc;
  border-radius: 4px;
  box-sizing: border-box;
}

.checkboxGroup {
  margin-left: 5px;
  margin-bottom: 15px;
}

.checkboxGroup label {
  display: block;
  margin-bottom: 6px;
}

.submitBtn {
  background: #0078d4;
  color: white;
  padding: 10px 18px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.submitBtn:hover {
  background: #005a9e;
}

.status {
  margin-top: 15px;
  font-weight: bold;
}
.errorInput {
  border: 2px solid red !important;
}

.errorBox {
  margin-top: 15px;
  padding: 12px;
  background: #ffe5e5;
  color: #b40000;
  border-left: 4px solid red;
  border-radius: 4px;
  font-size: 14px;
}

6. Once the implementation is done, run the gulp serve command to test this web part locally. The web part will be displayed as shown in the image below.
7. When we click the Submit button without entering any input in the form fields, custom error messages will be displayed below it, as shown in the image below. After filling out the form with the correct data and clicking the submit button, the file and metadata will be uploaded to the SharePoint library.

This way, you can upload files to a document library along with metadata using SPFx.

Conclusion

I hope you found this tutorial helpful. Here, I explained how to upload files to the SharePoint document library along with metadata using the PnPJS library in the SPFx web part. Also, I covered adding validations to the form before submitting to collect the required metadata fields.

You can download this solution and test it. If you face any issues with this, you can post your doubts in the comments below. Follow the steps mentioned in this article if you are also looking to upload files to the document library with metadata using SPFx.

You may also like the following related tutorials:

• Fluent UI DocumentCard in SPFx Web Part
• Create Folders and Subfolders in SharePoint document library using SPFx
• SPFx Field Customizer Example
• Get Current SharePoint Site Information in SPFx using MS Graph API
• Build a Custom Slides Manager in SPFx Web Part Property Pane (Drag & Drop, Reorder, Hide Slides)

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com

Here, the main requirement is that, for this web part, we need to allow users to choose which slides to display in the carousel. For the best practices, I took reference from the SharePoint Hero web part.

As you can see in the property pane, after selecting the SharePoint list and fields, the information was displayed under the slides. I can now easily drag and drop to reorder which slide needs to be visible first. Also, through menu items, I can move up or down. Additionally, I can remove the slides I don’t want displayed in the web part and even restore them.

In this tutorial, we’ll build a custom slide manager inside the SPFx property pane, similar to the SharePoint Hero web part.

By the end of this article, you’ll learn how to:

• Show dynamic items (slides) inside the property pane
• Reorder slides using drag and drop
• Move slides up or down
• Temporarily remove slides without deleting list items
• Restore hidden slides later
• Keep everything in sync with the web part UI

You can reuse this in carousels, banners, hero sections, and announcement web parts.

Want to learn SharePoint Framework development? Check out the SPFx training course.

Build a Slide Manager in SPFx Property Pane Using React

Before starting the implementation, let’s have a look at the SharePoint list I took for this SPFx web part. We’ll mainly focus on how to manage the slides on the SPFx web part property pane.

Below is the SharePoint list named “Company Announcements” having the following fields:

• Title = Default title field.
• Announcement Image = Image field.
• Announcement Link = Hyperlink field.

This way, im storing the announcement information for the SPFx web part.

Now, look at the SPFx web part property pane example below. I gave some configurations.

• Select List or Library = This dropdown lets you choose a SharePoint list or library available on the SharePoint site.
• Number of Items to Display = Allows selection of the number of items to display in the carousel web part.
• Title Field = Allows selection of the Image Title field.
• Image Field = Allows selection of an image field.
• Link Field = Allows selection of the Hyperlink field.
• Autoplay = Control the carousel’s moving slides.
• Slides = To display the items from the SharePoint list that are going to be visible in the web part. Here, we can drag and drop, move slides up and down, and either remove or restore slides.
  
  

Now let’s see the implementation.

I hope by this time, you know how to create an SPFx web part with the React framework; if not, follow this article.

1. Once the web part is created, run the following npm command to install the PnPJS.

npm install @pnp/sp --save

We are using this to interact with the SharePoint list for fetching items.

2. Run the command below to install PnP Property pane controls; this will auto-populate SharePoint lists, fields, etc.

npm install @pnp/spfx-property-controls --save

3. After that, open the Props.ts file and add the following code.

export interface ISpFxCarouselProps {
  description: string;
  isDarkTheme: boolean;
  environmentMessage: string;
  hasTeamsContext: boolean;
  userDisplayName: string;
  autoplayEnabled: boolean;
}

4. Then, we need to create some folders and files for the slides management in the property pane. So, as shown in the image below, add the folders and files.
   • models [Folder] = Under this path “src/webparts/spFxCarousel/”
     • ISlidesConfig.ts [File] = In this path “src/webparts/spFxCarousel/models/”
   • propertyPane [Folder] = Under this path “src/webparts/spFxCarousel/”
     • ISlidesConfig.ts [File] = In this path “src/webparts/spFxCarousel/propertyPane/”
     • PropertyPaneSlidesManager.ts [File] = In this path “src/webparts/spFxCarousel/propertyPane/”
     • SlidesManager.tsx [File] = In this path “src/webparts/spFxCarousel/propertyPane/”

5. Open the ISlideConfig.ts file located in the models folder.

export interface ISlideConfig {
  id: number;     
  visible: boolean; 
}

• id: The SharePoint list item ID (matches the “Id” column)
• visible: true = slide is shown in the carousel, false = slide is hidden

6. Then, open the ISlidesManagerProps.ts file located in the propertyPane folder.

import { ISlideConfig } from '../models/ISlidesConfig';

export interface ISlidesManagerProps {
  slidesConfig: ISlideConfig[];                      
  allItems: { id: number; title: string }[];        
  onConfigChanged: (config: ISlideConfig[]) => void; 
}

Here:

• This file stores the Props interface for the SlidesManager React component.
• These props are passed from PropertyPaneSlidesManager.ts when the component is created.
• slidesConfig = Current slide order and visibility (from web part properties)
• allItems = All items fetched from the SharePoint list (used to display titles)
• onConfigChanged = Callback to save changes back to the web part property bag

7. Add the code below to the PropertyPaneSlidesManager.ts file located in the propertyPane folder.

import * as React from 'react';
import * as ReactDom from 'react-dom';
import {
  IPropertyPaneField,
  IPropertyPaneCustomFieldProps,
  PropertyPaneFieldType
} from '@microsoft/sp-property-pane';
import { SlidesManager } from './SlidesManager';
import { ISlidesManagerProps } from './ISlidesManagerProps';
import { ISlideConfig } from '../models/ISlidesConfig';


export interface IPropertyPaneSlidesManagerConfig {
  key: string;                                       
  slidesConfig: ISlideConfig[];                      
  allItems: { id: number; title: string }[];         
  onConfigChanged: (config: ISlideConfig[]) => void; 
}

export function PropertyPaneSlidesManager(
  config: IPropertyPaneSlidesManagerConfig
): IPropertyPaneField<IPropertyPaneCustomFieldProps> {

  return {
   
    type: PropertyPaneFieldType.Custom,
    targetProperty: 'slidesConfig',

    properties: {
      key: config.key,
      onRender: (elem: HTMLElement) => {
        const el = React.createElement(SlidesManager, {
          slidesConfig: config.slidesConfig,
          allItems: config.allItems,
          onConfigChanged: config.onConfigChanged
        } as ISlidesManagerProps);

        ReactDom.render(el, elem);
      },

      onDispose: (elem: HTMLElement) => {
        ReactDom.unmountComponentAtNode(elem);
      }
    }
  };
}

Here:

• This file defines the config interface for creating this custom property pane field.
• IPropertyPaneSlidesManagerConfig:
  • key = Unique key for the property pane field (required by SPFx)
  • slidesConfig = Current slide order and visibility
  • allItems = All SharePoint list items (id + title)
  • onConfigChanged = Callback when user changes slide order or visibility
• PropertyPaneSlidesManager() = Creates a custom SPFx property pane field.
  • Because SPFx only supports built-in fields (dropdowns, toggles, etc.) by default.
  • To render our own React component (SlidesManager) inside the property pane,
  • we use PropertyPaneFieldType.Custom and manually mount the React component.
  • type: PropertyPaneFieldType.Custom = Tell SPFx that this is a custom field, not a built-in one.
  • targetProperty: ‘slidesConfig’ = The web part property this field is associated with.
  • onRender() under properties{} = Called by SPFx when the property pane needs to display this field.
  • We create the SlidesManager React component and mount it into the provided DOM element.

8. Then add the code below to the SlidesManager.tsx file present in the propertyPane folder.

import * as React from 'react';
import { ISlidesManagerProps } from './ISlidesManagerProps';
import { ISlideConfig } from '../models/ISlidesConfig';
import { IconButton } from '@fluentui/react/lib/Button';


interface IState {
  config: ISlideConfig[];
}

export class SlidesManager extends React.Component<ISlidesManagerProps, IState> {

  
  private dragIndex: number | null = null;
  private dragOverIndex: number | null = null;

  constructor(props: ISlidesManagerProps) {
    super(props);
    this.state = { config: props.slidesConfig.slice() };
  }


  public componentDidUpdate(prev: ISlidesManagerProps): void {
    if (JSON.stringify(prev.slidesConfig) !== JSON.stringify(this.props.slidesConfig)) {
      this.setState({ config: this.props.slidesConfig.slice() });
    }
  }

 
  public render(): JSX.Element {

    const visible: ISlideConfig[] = [];
    const hidden: ISlideConfig[] = [];

    for (const c of this.state.config) {
      c.visible ? visible.push(c) : hidden.push(c);
    }

    return (
      <div style={{ marginTop: 8 }}>

    
        {visible.map((c, index) => {

          let item = null;
          for (let i = 0; i < this.props.allItems.length; i++) {
            if (this.props.allItems[i].id === c.id) {
              item = this.props.allItems[i];
              break;
            }
          }
          if (!item) return null;

          return (
            <div
              key={c.id}
              draggable
              onDragStart={(e) => { this.dragIndex = index; e.dataTransfer.effectAllowed = 'move'; }}
              onDragEnter={() => this.dragOverIndex = index}
              onDragOver={(e) => { e.preventDefault(); e.dataTransfer.dropEffect = 'move'; }}
              onDrop={(e) => { e.preventDefault(); this.onDrop(); }}
              onDragEnd={() => { this.dragIndex = this.dragOverIndex = null; }}
              style={{
                display: 'flex',
                alignItems: 'center',
                padding: '6px 0',
                borderBottom: '1px solid #edebe9',
                cursor: 'grab'
              }}
            >

              <span style={{ padding: '0 6px', color: '#605e5c' }}>⋮⋮</span>

              {/* Slide title */}
              <span style={{
                flex: 1,
                fontSize: 13,
                overflow: 'hidden',
                whiteSpace: 'nowrap',
                textOverflow: 'ellipsis'
              }}>
                {item.title}
              </span>

             
              <IconButton
                iconProps={{ iconName: 'Hide3' }}
                title="Remove"
                onClick={() => this.hide(c.id)}
              />
            </div>
          );
        })}

 
        {hidden.length > 0 && (
          <div style={{ marginTop: 10 }}>
            <strong style={{ fontSize: 12 }}>Hidden slides</strong>

            {hidden.map(h => {

              let item = null;
              for (let i = 0; i < this.props.allItems.length; i++) {
                if (this.props.allItems[i].id === h.id) {
                  item = this.props.allItems[i];
                  break;
                }
              }
              if (!item) return null;

              return (
                <div key={h.id} style={{ fontSize: 13, marginTop: 4 }}>
                  {item.title}
                  <IconButton
                    iconProps={{ iconName: 'RedEye' }}
                    title="Show"
                    onClick={() => this.restore(h.id)}
                  />
                </div>
              );
            })}
          </div>
        )}
      </div>
    );
  }


  private onDrop = (): void => {
    if (this.dragIndex === null || this.dragOverIndex === null) return;
    if (this.dragIndex === this.dragOverIndex) {
      this.dragIndex = this.dragOverIndex = null;
      return;
    }

    const visible: ISlideConfig[] = [];
    const hidden: ISlideConfig[] = [];

    for (const c of this.state.config) {
      if (c.visible) visible.push(c);
      else hidden.push(c);
    }

    const dragged = visible.splice(this.dragIndex, 1)[0];
    visible.splice(this.dragOverIndex, 0, dragged);

    const newConfig = [...visible, ...hidden];

    this.update(newConfig);
    this.dragIndex = this.dragOverIndex = null;
  };

 
  private hide(id: number): void {
    const updated: ISlideConfig[] = [];

    for (const c of this.state.config) {
      updated.push(
        c.id === id ? { id: c.id, visible: false } : c
      );
    }

    this.update(updated);
  }


  private restore(id: number): void {
    const updated: ISlideConfig[] = [];

    for (const c of this.state.config) {
      updated.push(
        c.id === id ? { id: c.id, visible: true } : c
      );
    }

    this.update(updated);
  }

  private update(config: ISlideConfig[]): void {
    this.setState({ config });
    this.props.onConfigChanged(config);
  }
}

Here:

• This file is a SlidesManager React component rendered inside the SPFx property pane.
• It lets the user:
  • See all visible slides in their current order
  • Drag-and-drop to reorder visible slides
  • Hide a visible slide (click the hide icon)
  • Restore a hidden slide (click the eye icon)
• dragIndex, dragOverIndex =These store the index of the item being dragged and the index it’s hovering over.
• constructor() = Initialize state with a copy of the slidesConfig from props
• componentDidUpdate() = Sync state when props change from outside.
• render() = Splits config into visible and hidden slides, then renders both sections.
• onDrop() = Handles the drag-and-drop reorder when a slide is dropped.
  • Takes the dragged item out of its old position and inserts it at the new position.
  • The final config is: reordered visible slides first, then hidden slides.
• restore() = Sets a hidden slide’s visible flag back to true
  • The slide moves from the “hidden” section back to the “visible” section.
• update() = Saves the new config to local state and notifies the parent
  • The parent callback (onConfigChanged) saves the config as a JSON string
  • back into the web part’s property bag.

9. Then open the .ts file located in “src/webparts/spFxCarousel/”, which is the main entry point, and replace it with the following code.

import * as React from "react";
import * as ReactDom from "react-dom";
import { Version } from "@microsoft/sp-core-library";
import {
  IPropertyPaneConfiguration,
  PropertyPaneDropdown,
  PropertyPaneToggle,
  IPropertyPaneDropdownOption,
} from "@microsoft/sp-property-pane";
import { BaseClientSideWebPart } from "@microsoft/sp-webpart-base";
import { IReadonlyTheme } from "@microsoft/sp-component-base";
import {
  PropertyFieldListPicker,
  PropertyFieldListPickerOrderBy,
} from "@pnp/spfx-property-controls/lib/PropertyFieldListPicker";
import { PropertyFieldNumber } from "@pnp/spfx-property-controls/lib/PropertyFieldNumber";
import SpFxCarousel from "./components/SpFxCarousel";
import { ISpFxCarouselProps } from "./components/ISpFxCarouselProps";
import { PropertyPaneSlidesManager } from "./propertyPane/PropertyPaneSlidesManager";
import { spfi, SPFx } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/lists";
import "@pnp/sp/items";

export interface ISpFxCarouselWebPartProps {
  selectedListId: string;      
  titleFieldName: string;       
  imageFieldName: string;       
  hyperlinkFieldName: string;  
  numberOfItems: number;        
  autoplayEnabled: boolean;     
  slidesConfig: string;     
}

export default class SpFxCarouselWebPart extends BaseClientSideWebPart<ISpFxCarouselWebPartProps> {

  
  private _isDarkTheme: boolean = false;                     
  private _sp = spfi();                                        
  private _titleFields: IPropertyPaneDropdownOption[] = [];    
  private _imageFields: IPropertyPaneDropdownOption[] = [];    
  private _linkFields: IPropertyPaneDropdownOption[] = [];     
  private _announcementItems: { id: number; title: string }[] = []; 

  public render(): void {
    const element: React.ReactElement<ISpFxCarouselProps> = React.createElement(
      SpFxCarousel,
      {
        description: "",
        isDarkTheme: this._isDarkTheme,
        environmentMessage: "",
        hasTeamsContext: !!this.context.sdks.microsoftTeams,
        userDisplayName: this.context.pageContext.user.displayName,
        autoplayEnabled: this.properties.autoplayEnabled,
      },
    );

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

  protected async onInit(): Promise<void> {
    await super.onInit();
    this._sp = spfi().using(SPFx(this.context));
    await this._loadFieldOptions();
  }

  
  protected onThemeChanged(theme: IReadonlyTheme | undefined): void {
    if (!theme) return;
    this._isDarkTheme = !!theme.isInverted;
  }

  protected async onPropertyPaneConfigurationStart(): Promise<void> {
    await this._loadFieldOptions();
    await this._loadAnnouncementItems();
  }

  
  private async _loadAnnouncementItems(): Promise<void> {
    if (!this.properties.selectedListId) {
      this._announcementItems = [];
      return;
    }


    const items = await this._sp.web.lists
      .getById(this.properties.selectedListId)
      .items.select("Id", this.properties.titleFieldName)
      .top(this.properties.numberOfItems || 5)();

    
    this._announcementItems = items.map((i: any) => ({
      id: i.Id,
      title: i[this.properties.titleFieldName],
    }));

   
    let slidesConfig: { id: number; visible: boolean }[] = [];
    try {
      slidesConfig = JSON.parse(this.properties.slidesConfig || "[]");
    } catch {
      slidesConfig = [];
    }

    const existingIds = new Set(slidesConfig.map((c) => c.id));
    let changed = false;

    for (const item of this._announcementItems) {
      if (!existingIds.has(item.id)) {
        slidesConfig.push({ id: item.id, visible: true });
        changed = true;
      }
    }

    if (changed) {
      this.properties.slidesConfig = JSON.stringify(slidesConfig);
    }
  }

  
  protected async onPropertyPaneFieldChanged(
    propertyPath: string,
    oldValue: any,
    newValue: any,
  ): Promise<void> {
    super.onPropertyPaneFieldChanged(propertyPath, oldValue, newValue);

    
    if (propertyPath === "selectedListId" && oldValue !== newValue) {
      this.properties.titleFieldName = "";
      this.properties.imageFieldName = "";
      this.properties.hyperlinkFieldName = "";
      this.properties.slidesConfig = "[]";
      this._announcementItems = [];

      await this._loadFieldOptions();
      this.context.propertyPane.refresh();
      return;
    }


    const isConfigured =
      this.properties.selectedListId &&
      this.properties.titleFieldName &&
      this.properties.imageFieldName &&
      this.properties.hyperlinkFieldName;

    if (isConfigured) {
      await this._loadAnnouncementItems();
      this.context.propertyPane.refresh();
    }
  }


  private async _loadFieldOptions(): Promise<void> {
    if (!this.properties.selectedListId) {
      this._titleFields = [];
      this._imageFields = [];
      this._linkFields = [];
      return;
    }

    this._titleFields = [{ key: "Title", text: "Title" }];
    this._imageFields = [{ key: "Image", text: "Image" }];
    this._linkFields = [{ key: "Link", text: "Link" }];
  }


  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    const groups: any[] = [];



    const configFields: any[] = [

      PropertyFieldListPicker("selectedListId", {
        label: "Select List or Library",
        selectedList: this.properties.selectedListId,
        includeHidden: false,
        orderBy: PropertyFieldListPickerOrderBy.Title,
        onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
        properties: this.properties,
        context: this.context as any,
        key: "listPicker",
      }),

      PropertyFieldNumber("numberOfItems", {
        key: "numberOfItems",
        label: "Number of items to display",
        value: this.properties.numberOfItems || 5,
        minValue: 1,
        maxValue: 50,
      }),
    ];

    if (this.properties.selectedListId) {
      configFields.push(
        PropertyPaneDropdown("titleFieldName", {
          label: "Title Field",
          options: this._titleFields,
          selectedKey: this.properties.titleFieldName,
        }),
        PropertyPaneDropdown("imageFieldName", {
          label: "Image Field",
          options: this._imageFields,
          selectedKey: this.properties.imageFieldName,
        }),
        PropertyPaneDropdown("hyperlinkFieldName", {
          label: "Link Field",
          options: this._linkFields,
          selectedKey: this.properties.hyperlinkFieldName,
        }),
        PropertyPaneToggle("autoplayEnabled", {
          label: "Enable Autoplay",
          onText: "On",
          offText: "Off",
        }),
      );
    }

    groups.push({
      groupName: "Configuration",
      groupFields: configFields,
    });

    

    const isConfigured =
      this.properties.selectedListId &&
      this.properties.titleFieldName &&
      this.properties.imageFieldName &&
      this.properties.hyperlinkFieldName;

    if (isConfigured && this._announcementItems.length > 0) {
      let slidesConfig: any[] = [];
      try {
        slidesConfig = JSON.parse(this.properties.slidesConfig || "[]");
      } catch {
        slidesConfig = [];
      }

    
      groups.push({
        groupName: "Slides",
        groupFields: [
          PropertyPaneSlidesManager({
            key: "slidesManager",
            slidesConfig,
            allItems: this._announcementItems,
            onConfigChanged: (cfg: any[]) => {
              this.properties.slidesConfig = JSON.stringify(cfg);
              this.render();
              this.context.propertyPane.refresh();
            },
          }) as any,
        ],
      });
    }


    return {
      pages: [
        {
          header: { description: "SPFx Carousel Property Pane" },
          groups,
        },
      ],
    };
  }

  protected get dataVersion(): Version {
    return Version.parse("1.0");
  }
}

Here:

• To retrieve SharePoint list items, we used the PnPJS library. So, at the start, we added the PnPJS import statements.
• ISpFxCarouselWebPartProps = Define the web part property interface.
  • selectedListId =  GUID of the selected SharePoint list
  • titleFieldName = Internal name of the column used for slide titles
  • imageFieldName = Internal name of the column used for slide images
  • hyperlinkFieldName = Internal name of the column used for slide links
  • numberOfItems = Max number of items to fetch from the list
  • autoplayEnabled = Whether the carousel auto-advances
  • slidesConfig = JSON string of ISlideConfig[] — stores slide order and visibility.
• _titleFields = Dropdown options for the Title field picker
• _imageFields = Dropdown options for the Image field picker
• _linkFields = Dropdown options for the Link field picker
• _announcementItems = List items fetched from SharePoint
• render() = Called automatically whenever a web part property changes.
• onInit() = Initializes the PnP SP instance with the current SPFx context so we can call SharePoint APIs.
• onPropertyPaneConfigurationStart() = Fires when the user opens the property pane. Loads field options and list items so the pane shows up-to-date data.
• _loadAnnouncementItems() = Fetches items from the selected SharePoint list. Uses PnP SP to query items, then syncs them into slidesConfig so new items appear automatically.
  • items = Query SharePoint, select only the Id and Title columns, limited by numberOfItems.
  • this._announcementItems = Map raw SharePoint response into a simple { id, title } array.
  • slidesConfig = Sync slidesConfig; any new list item not already in slidesConfig gets added as visible.
• onPropertyPaneFieldChanged() = Fires whenever the user changes any property pane field.
  • Handles two scenarios: list change (reset everything) or field mapping change (reload items).
  • If the user picked a different list, reset all field mappings and slides.
  • If all four required fields are configured, fetch items and refresh the pane
• _loadFieldOptions() = Populates the dropdown options for Title, Image, and Link fields.
  • When no list is selected, the dropdowns are empty. Otherwise, they show the available columns.
• getPropertyPaneConfiguration() =  Builds the entire property pane UI.
  • Returns the configuration object that SPFx uses to render the property pane panel.
  • configFields = “Configuration” group, always visible
    • PropertyFieldListPicker =  List picker dropdown, shows all lists/libraries in the current site.
    • PropertyFieldNumber = Number field, how many items to fetch from the list.
  • this.properties.selectedListId = Field mapping dropdowns, only shown after a list is selected
  • isConfigured = “Slides” group, only shown when all fields are configured, AND items exist.
  • PropertyPaneSlidesManager = Renders the custom SlidesManager component inside the property pane. When the user reorders or hides/shows slides, onConfigChanged saves the new config.

This way, you can easily build a drag & drop slide on the SPFx web part property pane.

Conclusion

In this post, we learned how to build a custom slide manager inside the SPFx property pane that lets editors reorder slides, move them up or down, remove them, and restore them later, all without touching the original SharePoint list items.

This approach works well when you’re building carousel or banner web parts and want to give users control similar to the SharePoint Hero web part. It keeps the editing experience simple, safe, and easy to manage.

If you’re working on advanced SPFx web parts and need better content control in the property pane, this pattern is worth using.

Also, you may like:

• SPFx Property Pane Controls
• Create Folders and Subfolders in SharePoint document library using SPFx
• SPFx Upload File to SharePoint Document Library With Metadata [Complete Example]
• Create SPFx Dynamic Accordion Webpart Using PnP Controls React

Bijay Kumar

Hey! I’m Bijay Kumar, founder of SPGuides.com and a Microsoft Business Applications MVP (Power Automate, Power Apps). I launched this site in 2020 because I truly enjoy working with SharePoint, Power Platform, and SharePoint Framework (SPFx), and wanted to share that passion through step-by-step tutorials, guides, and training videos. My mission is to help you learn these technologies so you can utilize SharePoint, enhance productivity, and potentially build business solutions along the way.

www.enjoysharepoint.com