SharePoint Framework (SPFx) Cascading Dropdown

If you’ve ever built an SPFx web part where users need to pick a Country first and then a State from that country — you already know the problem. Show all 50 states upfront, and you’ll confuse users. That’s exactly where a cascading dropdown saves the day.

In this tutorial, I’ll walk you through building a cascading dropdown in an SPFx web part property pane using two real SharePoint lists — a Country list and a State list. When a user picks a country, the state dropdown automatically loads only the states that belong to that country.

If you are new to SPFx and want to learn SharePoint Framework development, check out the complete SharePoint Framework development training course.

Let me show you exactly how to set this up, step by step.

A cascading dropdown (also called a dependent dropdown) is when the options in one dropdown change based on what you pick in another dropdown.

For example:

You pick United States in the Country dropdown
The State dropdown immediately updates to show only California, Texas, New York, Florida, etc.
If you switch to Canada, the options change to Ontario, British Columbia, Quebec, and so on.

This is a really common pattern in SharePoint web parts, especially for forms or configuration panels.

What We’re Building

Here’s the full scenario:

Input: User opens the web part property pane and selects a country from the Country dropdown.

Output: The State dropdown automatically loads and shows only the states that belong to the selected country. The user can then pick a state, and both values are displayed in the web part body.

SharePoint Lists We’ll Use

Before we touch any code, let’s get our two SharePoint lists ready. These are the data source for our dropdowns.

List 1: Country

Create a SharePoint list called Country with a Title column (default).

ID	Title
1	United States
2	Canada
3	United Kingdom

List 2: State

Create a SharePoint list called State with two columns:

Title — the state name
Country — a Lookup column that points to the Country list

ID	Title	Country
1	California	United States
2	Texas	United States
3	New York	United States
4	Florida	United States
5	Ontario	Canada
6	British Columbia	Canada
7	Quebec	Canada
8	England	United Kingdom
9	Scotland	United Kingdom

spfx-cascading-dropdown-project-structure

That’s it. No fancy setup needed. Just these two lists with the data above.

Prerequisites

Before we start coding, make sure you have:

Node.js (v18.x LTS recommended as of 2025–2026)
SharePoint Framework Yeoman generator installed (@microsoft/generator-sharepoint)
Heft installed globally
Access to a SharePoint Online site where you’ve created the two lists above
Basic familiarity with TypeScript and React

If you need to set up your dev environment from scratch, check the official Microsoft docs for SPFx setup — it takes about 15 minutes.

Step 1: Scaffold a New SPFx Project

Open your terminal and run:

md spfx-cascading-dropdown
cd spfx-cascading-dropdown
yo @microsoft/sharepoint

When the Yeoman generator asks you questions, answer like this:

Solution name: spfx-cascading-dropdown
Type of client-side component: WebPart
Web part name: CountryState
Template: React

What Is a Cascading Dropdown?